AudioLink Reference Guide

You can create a basic AudioLink implementation in just a few lines of code with just a IAudioLinkFactory definition and registration. However, other API types can help you further build out your implementation.

Below you'll find summaries of each of the core AudioLink C++ types and some code examples.

IAudioLinkFactory

Every AudioLink implementation needs a factory class derived from IAudioLinkFactory, which has several pure virtual functions that define the implementation's entry points.

You must implement each function, as returning null results in an assert. Unreal Engine (UE) expects all calls dispatched to be thread-safe and ideally lockless to return efficiently.

You can use parameter structs instead of numerous individual parameters to simplify the extension of these function calls.

Plugin Implementation

AudioLink uses the IModularFeature interface to extend UE. The IAudioLinkFactory constructor handles registration, so creating an instance of your factory is sufficient for recognition. Handle this in the StartupModule() of your implementation.

Example: Submix AudioLink Implementation

// Parameters use when creating a Submix Audio Link 
struct FAudioLinkSubmixCreateArgs
{
    TWeakObjectPtr<const USoundSubmix> Submix;
    FAudioDevice* Device = nullptr;
    TWeakObjectPtr<const UAudioLinkSettingsAbstract> Settings;
};

// Create a Submix Audio Link.
// @param InCreateArgs Arguments used to create the AudioLink instance
// @return The newly created Link instance (if successful).
virtual TUniquePtr<IAudioLink> CreateSubmixAudioLink(const FAudioLinkSubmixCreateArgs& InCreateArgs) = 0;

    /**
    * Parameters use when creating a Submix Audio Link 
    */
    struct FAudioLinkSubmixCreateArgs
    {
        TWeakObjectPtr<const USoundSubmix> Submix;
        FAudioDevice* Device = nullptr;
        TWeakObjectPtr<const UAudioLinkSettingsAbstract> Settings;
    };

    /**
    * Create a Submix Audio Link.
    * @param InCreateArgs Arguments used to create the AudioLink instance
    * @return The newly created Link instance (if successful).
    */
    virtual TUniquePtr<IAudioLink> CreateSubmixAudioLink(const FAudioLinkSubmixCreateArgs& InCreateArgs) = 0;

Example: Factory Implementation

    class FAudioLinkExampleFactory : public IAudioLinkFactory
    {
    public:
        FAudioLinkExampleFactory() = default;
        virtual ~FAudioLinkExampleFactory() = default;

        static FName GetFactoryNameStatic();

    protected:
        /** Begin IAudioLinkFactory */
        FName GetFactoryName() const override;
        TSubclassOf<UAudioLinkSettingsAbstract> GetSettingsClass() const override;
        TUniquePtr<IAudioLink> CreateSubmixAudioLink(const FAudioLinkSubmixCreateArgs&) override;
        TUniquePtr<IAudioLink> CreateSourceAudioLink(const FAudioLinkSourceCreateArgs&) override;
        FAudioLinkSourcePushedSharedPtr CreateSourcePushedAudioLink(const FAudioLinkSourcePushedCreateArgs&) override;
        FAudioLinkSynchronizerSharedPtr CreateSynchronizerAudioLink() override;
        /** End IAudioLinkFactory */
    };

UAudioLinkSettingsAbstract

Every AudioLink implementation needs a settings class derived from UAudioLinkSettingsAbstract to create links with associated data, like buffer sizes, handshakes, and UAsset references.

Example: Settings Implementation

    UCLASS(config = Engine, defaultconfig)
    class AUDIOLINKEXAMPLERUNTIME_API UAudioLinkSettingsExample : public UAudioLinkSettingsAbstract
    {
        GENERATED_BODY()

        UPROPERTY(Config, EditAnywhere, Category = "Example|AudioLink")
        float MyBufferSize = 1.0f;
    };

    class FAudioLinkSettingsProxyExample : public IAudioLinkSettingsProxy
    {
    public:
        FAudioLinkSettingsProxyExample(const UAudioLinkSettingsExample&);
        virtual ~FAudioLinkSettingsProxyExample() = default;

        float GetMyBufferSize() const { return MyBufferSize; }

    private:
    #if WITH_EDITOR
        void RefreshFromSettings(UAudioLinkSettingsAbstract* InSettings, FPropertyChangedEvent& InPropertyChangedEvent) override
        {   
            MyBufferSize = CastChecked<UAudioLinkSettingsExample>(InSettings)->MyBufferSize;
        }
    #endif //WITH_EDITOR

        float MyBufferSize = 0;
    };

IAudioLinkSettingsProxy

AudioLink Settings follow a proxy design pattern, so they can safely exist outside the game thread where audio typically executes. A thread-safe copy of the settings is created and attached as a shared pointer to the setting's UObject.

This approach has two primary benefits.

• It provides garbage collection protection, as any threads that still have the shared pointer can continue to operate safely.

• PostEditChangedProperty automatically ferries data to the proxy when changes are made in the editor so that settings can behave like a standard asset.

All AudioLink Settings assets must implement a proxy of themselves and handle refreshing when the owning Asset changes via the RefreshFromSettings function.

Additionally, you should implement default settings for your properties, which serializes in the DefaultEngine.ini. In the Example: Settings Implementation, this is achieved via the defaultconfig markup on the settings object.

UFactory Implementation

Unreal Engine serializes AudioLink Settings as an asset. As a result, you are responsible for implementing an asset factory for the settings class so you can create the asset.

Example: Standard Settings Factory Implementation

    class FAssetTypeActions_AudioLinkExampleSettings : public FAssetTypeActions_Base
    {
        public:
            virtual FText GetName() const override;
            virtual FColor GetTypeColor() const override;
            virtual const TArray<FText>& GetSubMenus() const override;
            virtual UClass* GetSupportedClass() const override;
            virtual uint32 GetCategories() override;
    };

    UCLASS(hidecategories = Object, MinimalAPI)
    class UAudioLinkExampleSettingsFactory : public UFactory
    {
        GENERATED_UCLASS_BODY()

        virtual UObject* FactoryCreateNew(UClass* Class, UObject* InParent, FName Name, EObjectFlags Flags, UObject* Context, FFeedbackContext* Warn) override;

        virtual uint32 GetMenuCategories() const override;
    };

IAudioLink

IAudioLink is the primary abstraction used by the IAudioLinkFactory and is often returned by a TUniquePtr. It's an opaque type designed to contain the hidden details of plugin-specific implementation and in a thread-safe shared pointer to both a consumer and producer. The consumer object maintains a weak reference to the producer and safely terminates the connection when the producer is deleted, typically when the link ends due to elapsing lifetime.

Example: Instance Implementation

    //* AudioLink Instance, a container holding shared pointers for lifetime management. */
    struct FExampleLink : IAudioLink
    {
        // Circular buffer (submix/source) that listening for new buffers
        FSharedBufferedOutputPtr ProducerSP; 

        // Example client
        FSharedExampleAudioInputClientPtr ConsumerSP;   

        // ...
    };

IAudioMixerPlatformInterface

When you register an AudioLink Factory with UE, an AudioLink Platform Mixer is instantiated and hooks into AudioLink instead of the platform's hardware. Traditionally, third-party libraries have had to modify .ini files to prevent this, but AudioLink makes this less troublesome.

IBufferedAudioOutput

Most AudioLink instances use a class derived from IBufferedAudioOutput to create a producer object. Internally, they function as a circular buffer of pulse-code modulation (PCM) data waiting to be drained by a consumer object.

Implementations of this interface are already defined in the source code (FBufferedSourceListener and FBufferedSubmixListener), so it's likely unnecessary to build your own derived versions of these types.

Often, the link is created before the format of the incoming audio is recognized. As a result, an OnFormatKnown delegate fires once the format is known. You should set the delegate and start playback when it occurs.

Lifetime of a Link Instance

The lifetime of a link instance depends on its type.

• A source link generally lives for the lifetime of a source's playback. Once over, the source is deleted, severing the link. This severance is mainly due to the format of the source potentially being different for every new source.

• A submix link is open while the submix is running, which is usually the application's runtime. This can lead to issues caused by instance lifetime, especially in the editor. See Troubleshooting for more information.

IAudioLinkSynchronizer

Every AudioLink implementation needs a synchronizer class derived from IAudioLinkSynchronizer, which contains registration and removal calls for setting various callbacks. This class synchronizes to another clock source, so UE and the external application can stay in sync.

You must provide thread-safe delegates for each of these callbacks:

• Suspend

• Resume

• OpenStream

• CloseStream

• BeginRender

• EndRender

Use OpenStream to notify UE of the format of an external AudioLink Factory. This notification is most useful for matching block / sample rates and channel counts.

Use BeginRender and EndRender to synchronize UE with the external renderer.

Example: Synchronizer Implementation

    struct FExampleSynchronizerAudioLink : IAudioLinkSynchronizer 
    {
        IAudioLinkSynchronizer::FOnSuspend      OnSuspend;
        IAudioLinkSynchronizer::FOnResume       OnResume;
        IAudioLinkSynchronizer::FOnOpenStream   OnOpenStream;
        IAudioLinkSynchronizer::FOnCloseStream  OnCloseStream;
        IAudioLinkSynchronizer::FOnBeginRender  OnBeginRender;
        IAudioLinkSynchronizer::FOnEndRender    OnEndRender;

        FRWLock RwLock;

        // ...

        #define MAKE_DELEGATE_FUNC(X)\
            FDelegateHandle Register##X##Delegate(const FOn##X::FDelegate& InDelegate) override\
            {\
                FWriteScopeLock WriteLock(RwLock);\
                return On##X.Add(InDelegate);\
            }\
            bool Remove##X##Delegate(const FDelegateHandle& InHandle) override\
            {\
                FWriteScopeLock WriteLock(RwLock);\
                return On##X.Remove(InHandle);\
            }

        MAKE_DELEGATE_FUNC(Suspend)
        MAKE_DELEGATE_FUNC(Resume)
        MAKE_DELEGATE_FUNC(OpenStream)
        MAKE_DELEGATE_FUNC(CloseStream)
        MAKE_DELEGATE_FUNC(BeginRender)
        MAKE_DELEGATE_FUNC(EndRender)

        #undef MAKE_DELEGATE_FUNC
    };