Struct NativeAudio.InitializationOptions

An option for Initialize(NativeAudio.InitializationOptions). Because it is a struct, start making it from defaultOptions to get a good default values.

This class is currently only contains options for Android. iOS options are fixed.

Namespace: E7.Native

Assembly: E7.NativeAudio.dll

Syntax

public struct InitializationOptions

Fields

androidAudioTrackCount

How many native sources to request for Android. Default to 3 when using defaultOptions. It directly translates to maximum concurrency you can have while staying unmixed.

Declaration

public int androidAudioTrackCount

Field Value

Type	Description
System.Int32

Remarks

Please read Problems on number of native sources if you would like to increase this and learn what risks you are getting into.

androidBufferSize

At native side playing an audio is essentially a little callback that ask for the next tiny bit of audio data. This callback is called when the previous bit were all pushed out to speaker.

The size of that bit is buffer size. It affects latency and stability of audio as it determines frequency of this callback, or amount of data hardware could push out at a time.

• If zero or negative, it uses buffer size exactly equal to device's native buffer size. In most case you would use -1 to enable this default and probably good behaviour.
• If odd number, it gets +1 to the next even number.
• If any other positive number, use that number.

See OptimizeBufferSize(Int32), which is a helper static method to get a buffer size that is more compatible with the device.

Declaration

public int androidBufferSize

Field Value

Type	Description
System.Int32

Remarks

If small, the device have to work harder to fill the audio buffer to sent out because the previous round was used up so fast. If the device can't the audio will be garbled.

If large, the device have more time to leisurely fill the buffer as the previous sent data has more to put out until the next round, however it results in increased audio latency.

defaultOptions

A good starting values to create custom options.

Declaration

public static readonly NativeAudio.InitializationOptions defaultOptions

Field Value

Type	Description
NativeAudio.InitializationOptions

Remarks

A struct cannot have default value on new, this statically allocated struct is prepared for you to copy from instead.

preserveOnMinimize

[Android]

• If false (a default on defaultOptions), on Initialize() the native side will remember the spec you request. On minimize it will dispose all the sources (and in turn stopping them). On coming back it will reinitialize with the same spec
• If true the allocated native sources will not be freed when minimize the app. (The Unity ones did free and request a new one on coming back)

[iOS] No effect, iOS's native sources is already minimize-compatible but its playing-when-minimized is prevented by the app's build option.

Declaration

public bool preserveOnMinimize

Field Value

Type	Description
System.Boolean

Remarks

[Android]

This make it possible for audio played with Native Audio to play while minimizing the app, and also to not spend time disposing and allocating sources again.

However this is not good since it adds "wake lock" to your game. With adb shell dumpsys power while your game is minimized after using Native Audio you will see something like PARTIAL_WAKE_LOCK 'AudioMix' ACQ=-27s586ms(uid= 1041 ws= WorkSource{ 10331}).

Meaning that the OS have to keep the audio mix alive all the time. Not to mention most games do not really want this behaviour.

Most gamers I saw also minimized the game and sometimes forgot to close them off. This cause not only battery drain when there is a wake lock active, but also when the lock turns into LONG state it will show up as a warning in Google Play Store, as it could detect that an app has a Stuck partial wake lock or not.

[iOS]

If you want the audio to continue to be heard in minimize, use "Behaviour in background" set as Custom - Audio in Unity Player Settings then follow this thread to setup the AVAudioSession to correct settings.

Methods

OptimizeBufferSize(Int32)

[Android] On using Initialize(NativeAudio.InitializationOptions) you could freely specify a custom buffer size that is not device's native buffer size.

However a buffer size too low with an intention to minimize latency may break audio or even crash, a buffer size too high with an intention to fix a problematic phone that report its own native buffer size wrong may not be a multiple of device's native buffer size causing jittering problem.

This method translate buffer size number into something potentially better for the device for you to use in initialization. Therefore the return value is device dependent and only usable at runtime.

• If bufferSize is lower than device's native buffer size, it will be clamped to device's native buffer size.
• If bufferSize is higher than device's native buffer size, you get back an even larger number which is the next nearest multiple of device's native buffer size. The reason is to reduce jitter as stated in here.

Example of larger case : Specified 256

• Xperia Z5 : Native buffer size : 192 -> what you get : 384
• Lenovo A..something : Native buffer size : 620 -> what you get : 620

[iOS] Returns the same buffer size. Note that iOS cannot specify custom buffer size as it shares the same size as you selected for Unity. (e.g. Best Latency = 256, etc.) This is why the option has been named as androidBufferSize.

Declaration

public static int OptimizeBufferSize(int bufferSize)

Parameters

Type	Name	Description
System.Int32	bufferSize

Returns

Type	Description
System.Int32