Name
BeginSampleStream -- create a new sample stream (V11.0)
Synopsis
APTR handle = BeginSampleStream(STRPTR filename, struct SaveSampleCtrl
                  *ctrl, struct hwTagList *tags);
Function
This function is optional and must only be implemented if the HWEXT_SAVESAMPLE_STREAM extension bit has been set. See Extension plugins for details. In that case, this function must create a new sample stream in the specified filename. After Hollywood has called this function, it will then call WriteSampleStream() to add PCM data to your sample stream. Once all PCM data has been added, Hollywood will call FinishSampleStream() on the stream handle.

Hollywood passes a pointer to a struct SaveSampleCtrl to this function. This structure looks like this:

 
struct SaveSampleCtrl
{
    APTR Data;                      // [unused]
    int DataSize;                   // [unused]
    int Samples;                    // [unused]
    int Channels;                   // [in]
    int Bits;                       // [in]
    int Frequency;                  // [in]
    ULONG Flags;                    // [in]
    ULONG FormatID;                 // [in]
    STRPTR Adapter;                 // [in]
    struct hwUserTagList *UserTags; // [in]
    int BitRate;                    // [in]
    int Quality;                    // [in]
};

In this structure Hollywood passes information about the encoding of the PCM samples that will be passed to your WriteSampleStream() function by Hollywood. The following information is passed to your BeginSampleStream() function:

Data:
This member is unused.

DataSize:
This member is unused.

Samples:
This member is unused.

Channels:
The number of channels used by the sound data. This will be either 1 (mono) or 2 (stereo).

Bits:
The number of bits per PCM sample. This will be either 8 or 16.

Frequency:
The number of PCM frames that should be played per second.

Flags:
A combination of the following flags describing additional properties of the sample:

HWSNDFLAGS_BIGENDIAN
The PCM samples are stored in big endian format. This flag is only meaningful if the bit resolution is 16.

HWSNDFLAGS_SIGNEDINT
The PCM samples are stored as signed integers. This is typically set for 16-bit samples.

FormatID:
This member contains the identifier of the sample format the file should be saved in. You only need to look at this member if your plugin supports more than one output sample format.

Adapter:
If this member is non-NULL, Hollywood wants your plugin to use the file adapter specified in Adapter to save the sample. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to save the sample.

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.

BitRate:
This member will be set to the value that the user has specified in the Bitrate tag when calling Hollywood commands such as SaveMusic(). If the user hasn't set the Bitrate tag, this member will be set to -1.

Quality:
This member will be set to the value that the user has specified in the Quality tag when calling Hollywood commands such as SaveMusic(). If the user hasn't set the Quality tag, this member will be set to -1.

This function has to return a handle to the stream if the sample stream has been successfully created or NULL if there was an error.

Inputs
filename
path to a destination file
ctrl
pointer to a struct SaveSampleCtrl containing information about the sample format
tags
reserved for future use; will always be NULL at the moment
Results
handle
stream handle or NULL in case of an error
Show TOC