StartAudioStream(object, int, string, int, float, float, float)

Starts an audio stream for a player.

void StartAudioStream(
    object oPlayer,
    int nStreamIdentifier,
    string sResRef,
    int bLooping = FALSE,
    float fFadeTime = 0.0f,
    float fSeekOffset = -1.0f,
    float fVolume = 1.0f
);

Parameters

oPlayer

The player to play an audio stream for.

nStreamIdentifier

Which AUDIOSTREAM_IDENTIFIER_* to start. There are 10 available in total.

sResRef

Audio file to play

bLooping

Should the audio loop or not (default: FALSE)

fFadeTime

The amount of seconds to gradually fade in the audio instead of starting directly (default: 0.0f)

fSeekOffset

Offset to seek in the file, in seconds. If -1.0 it plays from the start. If fSeekOffset is at or beyond the end of the stream, the seek offset will wrap around, even if the file is configured not to loop. (default: -1.0f)

fVolume

Volume of the audio stream. This is modified by the player-side option for it as well. (0.0 - 1.0, default: 1.0f)

Description

Assign one of the available audio streams to play a specific file. This mechanism can be used to replace regular music playback, and synchronize it between clients.

There is currently no way to get playback state from clients.

Audio streams play in the streams channel which has its own volume setting in the client.

Currently, only MP3 CBR files are supported and properly seekable.

Unlike regular music, audio streams do not pause on load screens.

Only one type of fading can be active at once, for example: If you call StartAudioStream() with fFadeTime = 10.0f, any other audio stream functions with a fade time >0.0f will have no effect until StartAudioStream() is done fading.

Remarks

This is a versatile way to have music follow between areas (eg the interior and exterior of the same thematic area), and to play different ambient tracks overlapping and perhaps changing volume on distance to things in the world since there are 10 tracks available.

Since it allows synced playing it also allows musical bands to functionally work with different players coming into the area at different times still having the same diegetic sounds playing. You could even overlap things so a lute plays in one track and drums in another so if the drummer stops then only their part of the music stops.

Since it also is a direct sound that is not tied to the 3d position of the camera, you can get a much clearer set of sounds playing - for instance voicelines - for cutscenes or similar aspects, without them being potentially weirdly quiet or loud.

Version

This function was added in 88.8193.36-11 of NWN:EE.

Example

// Plays the audio track "mus_ruralday1" on a loop forever using track 0
void main()
{
    object oPC = GetFirstPC();

    StartAudioStream(oPlayer, AUDIOSTREAM_IDENTIFIER_0, "mus_ruralday1", TRUE, 0.0, -1.0, 1.0);
}

See Also

functions:

StopAudioStream SetAudioStreamPaused SetAudioStreamVolume SeekAudioStream