APTR handle = OpenStream(STRPTR filename, struct LoadSoundCtrl *ctrl);

This function also has to provide certain information about the sound file it has just opened. This information has to be written to the struct LoadSoundCtrl that is passed in the second parameter. This structure looks like this:

struct LoadSoundCtrl { ULONG Samples; // [out] int Channels; // [out] int Bits; // [out] int Frequency; // [out] ULONG Flags; // [out] int SubSong; // [in] -- V5.3 int NumSubSongs; // [out] -- V5.3 STRPTR Adapter; // [in] -- V6.0 struct hwUserTagList *UserTags; // [in] -- V10.0 };

The following information has to be written to the struct LoadSoundCtrl pointer by OpenStream():

Samples:

The total number of PCM frames in the sound file. This can be 0 if you set the HWSNDFLAGS_INFINITE flag (see below).

Channels:

The number of channels used by the sound file. This must be either 1 (mono) or 2 (stereo).

Bits:

The number of bits per PCM sample. This must be either 8 or 16.

Frequency:

The number of PCM frames that should be played per second. Usually 44100 or 48000.

Flags:

A combination of the following flags describing additional properties of the stream:

HWSNDFLAGS_BIGENDIAN

The PCM samples are stored in big endian format. This flag is only meaningful if the bit resolution is 16. This flag is unsupported on Windows, AROS x86, and Android.

HWSNDFLAGS_SIGNEDINT

The PCM samples are stored as signed integers. This flag must always be set for 16-bit samples. For 8-bit samples this flag is unsupported on Windows, Linux and Android, i.e. 8-bit samples must always be unsigned on these three platforms. On all other platforms this flag must be set for 8-bit samples and the samples must be signed.

HWSNDFLAGS_CANSEEK

Plugin supports seeking directly to PCM frames using SeekStream(). Note that even if this flag isn't set, your plugin still needs to be able to rewind the stream, i.e. seek it back to the very beginning when 0 is passed to SeekStream(). See SeekStream for details.

HWSNDFLAGS_INFINITE:

Set this flag to tell Hollywood that this stream will loop forever and will never finish. In that case you also have to set Samples to 0. (V9.0)

SubSong:

This member will be set by Hollywood to the sub-song within the sound file that Hollywood wants your plugin to open. Only useful for old tracker modules. (V5.3)

NumSubSongs:

This must be set by your plugin to the total number of sub-songs in the sound file. This is typically set to 1 because most sound file formats do not support sub-songs. This feature is only here to allow support for old tracker module formats that can have various sub-songs in the same file. (V5.3)

Adapter:

Starting with Hollywood 6.0 users can specify the file adapter that should be used to open certain files. If this member is non-NULL, Hollywood wants your plugin to use the file adapter specified in Adapter to open the sound file. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the sound file. Make sure to check for Hollywood 6.0 before trying to access this member because it isn't there in previous versions. See hw_FOpenExt for details. (V6.0)

UserTags:

This member will be set to a list of user tags in case they were specified in the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. Note that even if your plugin doesn't support any user tags, you should still look for this tag and pass the user tags to hw_FOpenExt because the user tags passed in UserTags could also be intended for another plugin, namely the file adapter plugin passed in Adapter. See User tags for details. Make sure to check for Hollywood 10.0 before trying to access this member because it isn't there in previous versions. (V10.0)

Please note that you should not use ANSI C functions like fopen() to open the file that is passed to this function because the filename that is passed to this function can also be a specially formatted filename specification that Hollywood uses to load files that have been linked to applets or executables. In order to be able to load these files correctly, you have to use special IO functions provided by Hollywood. See File IO information for details.

filename

filename to open

ctrl

pointer to a struct LoadSoundCtrl for storing information about the sound file

handle

a handle that identifies this sound file or NULL if plugin doesn't want to handle this sound file