# NNS_SndArcStrmPrepareEx2

## Syntax

      #include <nnsys/snd.h>

      BOOL NNS_SndArcStrmPrepareEx2(
              NNSSndStrmHandle* handle,
              int playerNo,
              int playerPrio,
              int strmNo,
              u32 offset,
              NNSSndStrmCallback strmCallback,
              void* strmCallbackArg,
              NNSSndArcStrmCallback sndArcStrmCallback,
              void* sndArcStrmCallbackArg );

## Arguments

`handle` | Pointer to a stream handle.
`playerNo` | Player number.
`playerPrio` | Player priority. The value is in the 0-127 range; a greater value indicates higher priority.
`strmNo` | Stream number.
`offset` | Starting offset position. Units are milliseconds.
`strmCallback` | Pointer to a stream callback function.
`strmCallbackArg` | User argument for the stream callback function.
`sndArcStrmCallback` | Pointer to the sound archive stream callback function.
`sndArcStrmCallbackArg` | User argument for the sound archive stream callback function.

## Return Values

If playback succeeds, `TRUE`; if it fails, `FALSE`.

## Description

Registers the callback functions and prepares a stream.

The sound archive stream library must be initialized in advance using the `NNS_SndArcStrmInit` function.

The stream handle `handle` needs to be initialized only once in advance using the `NNS_SndStrmHandleInit` function. Calling this function releases the stream already attached to the stream handle (this does not mean it is stopped). If playback succeeds, the stream is attached to the stream handle.

If -1 is specified for the player number `playerNo` and player priority `playerPrio`, the parameters specified with the sound data are used.

If a non-zero value is set for the start offset position `offset`, it is possible to play from the middle of the stream data.

The stream callback function `strmCallback` is periodically called during playback. Playback waveform data can be processed in this callback function. The user argument to the stream callback function, `strmCallbackArg`, is passed unchanged to `strmCallback`. If registration of the stream callback function is not required, specify `NULL`. Refer to the description of `NNSSndStrmCallback` for information on the stream callback function.

The sound archive stream callback function `sndArcStrmCallback` is called at a specified time. With it, you can connect multiple stream data and play them in real time. The user argument to the sound archive stream callback function, `sndArcStrmCallbackArg`, is passed unchanged to `sndArcStrmCallback`. If registration of the sound archive stream callback function is not required, specify `NULL`. Refer to the description of `NNSSndArcStrmCallback` for information on the sound archive stream callback function.

You can check whether the preparations are completed with the `NNS_SndArcStrmIsPrepared` function. Call the `NNS_SndArcStrmStartPrepared` function to play back streams for which preparations are completed.

The channels used for stream playback are allocated internally by this function. If the allocated channels were being used by sequence playback, the audio being produced is forcibly stopped. To control the timing of when channels are allocated, call the `NNS_SndArcStrmAllocChannel` function in advance.

If the stream data is in stereo, channel 0 is output from the left and channel 1 from the right. These settings can be changed with the ``NNS_SndArcStrmSetChannelPan`` function.

Playback failure may be the result of the following factors:

- The stream number is invalid.
- The priority is lower than the stream already being played.
- The channels used by the stream player are already being used for another purpose.

## See Also

`NNS_SndArcStrmInit, NNS_SndStrmHandleInit, NNSSndStrmCallback, NNSSndArcStrmCallback, NNS_SndArcStrmIsPrepared, NNS_SndArcStrmStartPrepared, NNS_SndArcStrmAllocChannel, NNS_SndArcStrmSetChannelPan`

## Revision History

2004/11/26 Initial version.

CONFIDENTIAL