Overview of the Advanced Sound Player

The advanced sound player contains a superset of the features of the original sound file player described in Chapter 5, "Playing Sound Files". In addition to the basic features offered by the original sound file player, playback of an AIFF file, the advanced sound player does the following:

Even though the advanced sound player completely supersedes the original sound file player, it does have slightly more code overhead than the original sound file player. This means that you may still wish to use the original sound file player if you simply want to play a single AIFF file once and have tight memory restrictions. Be aware, though, that the advanced sound player is more actively supported with regard to future enhancements than the original sound file player.

It is worth reading the discussion of spooling sound from disc in Chapter 5, as the same concepts apply to the advanced sound player.

Simple Advanced Sound Player Example

This annotated advanced sound player example demonstrates how to play an AIFF sound file through once. Error checking was eliminated for brevity. More complicated examples are built from this one later in this chapter.

  1. Preparation. Note that this step makes a number of assumptions about the kinds of sounds that are going to be played and how to direct the output signal to the 3DO audio output. In this case, we are expecting to play a monophonic 16-bit 44KHz sample and are connecting it directly to the audio output. In practice, you may need to select a different sample player instrument or an alternate method of directing the output.

    samplerins = LoadInstrument ("fixedmonosample.dsp", 0, 100);
    outputins = LoadInstrument ("directout.dsp", 0, 100);
    ConnectInstruments (samplerins, "Output", outputins, "InputLeft");
    ConnectInstruments (samplerins, "Output", outputins, "InputRight");
    StartInstrument (outputins);

  2. Create a player.

    spCreatePlayer (&player, samplerins, NUMBUFFS, BufSize, NULL);

  3. Specify an AIFF sound file to play.

    spAddSoundFile (&sound, player, filename);

  4. Set up branches. In this example, there are no branches to set up, so this step is simply a placeholder. Examples of looping and branching shows how to modify this example to do more interesting kinds of playback.

  5. Start reading sound. This step prefills the spooler with sound data so that the next step can begin producing sound immediately.

    spStartReading (sound1, SP_MARKER_NAME_BEGIN);

  6. Start playing sound.

    spStartPlayingVA (player,
    AF_TAG_AMPLITUDE, 0x7fff,
    TAG_END);

  7. Service the player by receiving its signals and calling spService(). Stay in this loop until sound playback is complete.

    const int32 playersigs = spGetPlayerSignalMask (player);

    while (spGetPlayerStatus(player) & SP_STATUS_F_BUFFER_ACTIVE)
    {
    const int32 sigs = WaitSignal (playersigs);
    spService (player, sigs);
    }

  8. Clean up. Note that spDeletePlayer() takes care of cleaning up anything that was given to it (e.g. the sound file added in step 3). This is more completely described in spDeletePlayer in Music Library Calls.

    spStop (player);
    spDeletePlayer (player);
    UnloadInstrument (outputins);
    UnloadInstrument (samplerins);