# NNS_SndStrmSetup

## Syntax

      #include <nnsys/snd.h>

      BOOL NNS_SndStrmSetup(
              NNSSndStrm* stream,
              NNSSndStrmFormat format,
              void* buffer,
              u32 bufSize,
              int timer,
              int interval,
              NNSSndStrmCallback callback,
              void* arg );

## Arguments

`stream` | Pointer to a stream structure.
`format` | Stream data format.
`buffer` | Address at the beginning of a stream buffer. Must have 32-byte alignment.
`bufSize` | Size of a stream buffer. It must be interval * (number of channels) * (a multiple of 32).
`timer` | The stream channel timer value.
`interval` | Callback interval. Specify a value of 2 or more.
`callback` | Pointer to a stream callback function.
`arg` | User argument for the stream callback function.

## Return Values

Returns a boolean value to indicate if the setup is successful.

## Description

Sets up a stream. Before using this function, you must allocate channels with the `NNS_SndStrmAllocChannel` function. To play the stream, call the `NNS_SndStrmStart` function after calling this function.

Select from the following stream formats (format). A 16-bit stream format offers better sound quality than an 8-bit stream format. However, when a 16-bit stream format is used, the callback function will be called twice as often as when an 8-bit stream format is used. In order to have the callback function called at the same frequency (as when an 8-bit stream format is used) when you are using a 16-bit stream format, you must prepare a stream buffer that is twice as large.

Table: NNSSndStrmFormat

Label | Description
--- | ---
NNS_SND_STRM_FORMAT_PCM8 | 8-bit PCM.
NNS_SND_STRM_FORMAT_PCM16 | 16-bit PCM.

A stream buffer is required for a stream to be played. The smaller the stream buffer is, the more often the callback is called. The first address in the stream buffer buffer must be 32-bit aligned. The stream buffer size bufSize must be `interval` * (number of channels) * (a multiple of 32). Here the number of channels is the number of channels allocated by the `NNS_SndStrmAllocChannel` function.

The stream channel timer value timer is a parameter that controls stream play speed. The unit for this value is the number of clock cycles that are required to play one sample. The number of clock cycles per second is defined as `NNS_SND_STRM_TIMER_CLOCK`. For example, in order to play with a sampling rate of sampleRate, specify a time value of `NNS_SND_STRM_TIMER_CLOCK` / sampleRate.

The callback interval interval specifies how many times a callback function will be called during the time that an entire stream buffer is played. For example, if you specify a value of 2, waveform data will be written into the remaining half of the buffer while half of the buffer is being played.

The callback function callback is called when waveform data must be filled. The callback function user argument `arg` is passed unchanged to the argument in the `callback` argument's callback function. Refer to the description of `NNSSndStrmCallback` for information on the stream callback function.

## See Also

`NNS_SndStrmAllocChannel`, `NNS_SndStrmStart`, `NNSSndStrmCallback`

## Revision History

2004/11/26 Separated out the description of `NNSSndStrmCallback`.
2004/08/10 Initial version.

CONFIDENTIAL