v1 AudioPlayer

AudioPlayer

Caution

This page is for v1 of SecretLabNAudio. v2 guide

The AudioPlayer component (attached to a SpeakerToy) handles audio reading & encoding.

To play the same audio through multiple speakers at once, create one AudioPlayer and set the other speakers' controller IDs to that of the player.

Audio samples are provided by a sample provider

The player keeps track of how many packets need to be sent using Time.deltaTime

At a stable 60 TPS, this means 1-2 packets every frame. 1 packet is 480 samples. When no samples are read, the buffer is cleared

The player reads audio if IsPaused is false and the provider is not null, regardless of send engine or output monitor

Right before encoding, the samples may be amplified regardless of provider or monitor.

Note

When the component is disabled, it will be reset, and the Destroyed event will be invoked. This usually happens when the speaker is pooled.

Tip

There are various extension methods to set properties on the audio player component. You can chain these methods as they return the AudioPlayer itself.

Execution Sequence

When a packet needs to be processed (at least 480 samples should be read), the method runs as follows, repeating until less than 480 samples are needed:

1. Return if IsPaused is true or if the SampleProvider is null
2. Read from the provider
3. If 0 samples were read:
   • Set HasEnded to true
   • Clear the buffer
   • Invoke the OutputMonitor's OnEmpty method
   • Invoke the NoSamplesRead event
   • Return
4. Clear the remainder of the buffer if less than 480 samples were read
5. Invoke the OutputMonitor's OnRead method
6. Return if the SendEngine is null
7. Amplify the read samples if MasterAmplification is not 1
8. Encode the samples with Opus
9. Pass the encoded data as an AudioMessage to the SendEngine

Instantiation

You can obtain an audio player by calling:

• AudioPlayerPool.Rent - recommended method, read more here
• AudioPlayer.Create
• the AddAudioPlayer extension method on a SpeakerToy

Properties

SampleProvider

This is the interface which provides audio samples. May be null.

Important

The provider (if not null) must have a wave format matching the following criteria:

• 48000 Hz sample rate
• mono (1 channel)
• IEEEFloat encoding

Use the WithProvider extension method to automatically downmix & resample to the correct format.

Tip

See also: providers and reading from files

Speaker

The SpeakerToy this component is attached to (read-only).

SendEngine

The send engine that will be used to broadcast audio messages. Set to null to disable encoding and broadcasting.

Defaults to SendEngine.DefaultEngine

OutputMonitor

An optional packet monitor that can analyze the outputted samples. null by default.

The output monitor (if set) is invoked even if no send engine is specified.

MasterAmplification

A volume scalar to multiply the samples by before encoding. The output monitor is not affected by this, meaning it'll observe the samples from the provider as if they were not amplified after reading.

This property lets you amplify the volume further without wrapping all providers into a VolumeSampleProvider

Note

This property is different from the volume of the SpeakerToy itself. It can be used to always amplify audio, allowing for easier personalization

IsPaused

When set to true, the player will pause, no updates will be performed.

HasEnded

true if the playback has finished during the previous update (fewer samples were read than requested).

Note

This value is not updated if the player is paused or if the provider is null.

Id

Gets or sets the controller ID of the speaker. If multiple speakers share the same ID, audio from the player will be heard from each of them.

Events

NoSamplesRead

Invoked when the provider reads 0 samples.

Before the event is invoked, HasEnded is set to true, the buffer is cleared, and the monitor's OnEmpty method is called.

Destroyed

Invoked when the component is destroyed. The event also gets called when the component is disabled (when the speaker is pooled).

Methods

ClearBuffer

Sets the remaining time to 0 and clears the provider's buffer if it's a BufferedSampleProvider

Destroy

Destroys the game object, removing the speaker and all of its components (including the audio player).

Exception Handling

If the provider throws an exception, it is logged with Unity's logger. The player treats this state as if no samples were read.

You can find Unity logs in the LocalAdmin logs directory:

• Linux: .config/SCP Secret Laboratory/LocalAdminLogs/<port>
• Windows: %appdata%/SCP Secret Laboratory/LocalAdminLogs/<port>