Name
CreateSample -- create a sample (V2.0)
Synopsis
[id] = CreateSample(id, table, pitch[, fmt, length])
Function
This function can be used to create a new sample from custom PCM data. The sample will be added to Hollywood's sample list and can be accessed by the specified id. If you pass Nil in id, CreateSample() will automatically select a vacant identifier and return it to you. You also have to specify the desired playback frequency for this sample in the pitch argument. The optional argument fmt allows you to specify the format of the PCM data you are about to pass to this function. Currently, the following formats are supported: #MONO8 (which is the default), #STEREO8, #MONO16, and #STEREO16. The optional argument length specifies the desired length in PCM frames for the new samples.

The sample data must be passed as signed integers. For 8-bit samples the valid sample range runs from -128 to 127, and for 16-bit samples the valid sample range runs from -32768 to 32767.

If you want to create a stereo sample, you must pass interleaved PCM data, i.e. left channel sample is followed by right channel sample is followed by left channel sample, and so on.

Starting with Hollywood 5.0, the PCM data can be passed to this function in a number of different ways. CreateSample() can use an array of PCM samples, an identifier of an open file, or a memory block as the source for the new sample. Which source is used depends on the setting in the table argument which accepts the following tags:

Source:
This tag specifies from which source CreateSample() should fetch the audio data for the sample. It must be set to a string that identifies the audio data source. The following sources are possible:

PCM
Fetch audio data directly from an array of PCM samples. If you specify this field, you must pass the PCM data in the same table starting at index 0. CreateSample() will then read length PCM frames from this table. If length is not specified, then CreateSample() will read all PCM frames from the table.

File
Fetch audio data from an open file. If you use this source type, you also need to specify a valid file identifier in the ID tag. It is also necessary to specify the optional length argument so that CreateSample() knows how many frames it should fetch from the specified file.

Memory
Fetch audio data from a memory block. If you use this source type, you also need to specify a valid memory block identifier in the ID tag. It is also necessary to specify the optional length argument so that CreateSample() knows how many frames it should fetch from the specified memory block.

The default value for the Source tag is PCM which means fetch the audio data from an array of PCM samples stored in the same table as these options.

ID:
This tag is only required for source types File and Memory. In that case, you need to pass a valid file / memory block identifier here.

Offset:
This tag can only be used in conjunction with source type Memory. In that case, it specifies an offset into the memory block at which CreateSample() should start fetching audio data. The offset is specified in bytes.

Swap:
This tag can only be used in conjunction with source types File and Memory and a sample depth of 16 bits. In that case, the Swap tag can be used to specify whether or not CreateSample() should swap the two bytes making up a 16 bit sample. This is required if the sample data in the file or memory block is encoded in little endian format (LSB first). CreateSample(), however, requires 16-bit sample data to be in big endian format (MSB first). So if your source can only provide sample data in LSB format, simply set the Swap tag to True and everything should be fine. This tag defaults to False which means do not swap anything.

Please note that the new sample should use at least 1000 PCM frames. If you use less frames, the playback in loop mode will become very CPU intensive. Even if your sample has only 32 different wave forms, you should concatenate them until your sample has at least 1000 frames for performance reasons.

If you pass large sample tables to this function, please do not forget to set these tables to Nil when you no longer need them. Otherwise you will waste great amounts of memory.

Starting with Hollywood 5.0, CreateSample() can also create empty samples if you pass an empty table or specify a length of zero. In that case, you can use functions like InsertSample() to fill the sample with audio data later.

Inputs
id
identifier for the new sample or Nil for auto selection
table
table containing parameters for the new sample
pitch
desired playback frequency for the sample
fmt
optional: format of the samples passed in argument 2 (defaults to #MONO8) (V5.0)
length
optional: desired length of the new sample in PCM frames (V5.0)
Results
id
optional: identifier of new sample; this is only used if Nil is passed in the first argument
Example
smpdata = {}
slen = 32
For k = 0 To 30
  For i = 0 To (slen\2)-1
    smpdata[k*slen+i] = -128
    smpdata[k*slen+i+(slen\2)] = 127
  Next
Next
CreateSample(1, smpdata, 6982)
PlaySample(1)
The code above creates a simple beep sound.

Show TOC