Sample

A digital recording of a sound.

Description

A Sample Item is a handle to a digital recording of a sound in memory. Samples come in two kinds:

Ordinary Samples - sample loaded from a sample file, or created from scratch. User memory is used for samples. CreateSample() and a myriad of special purpose functions create ordinary samples.
Delay Lines - special samples suitable for receiving the DMA output from delay instruments (e.g. delaymono.dsp). The memory for delay lines is allocated in system memory. Use CreateDelayLine() to create a delay line.

Most sample operations can be performed on both kinds of samples.

Folio

audio

Item Type

AUDIO_SAMPLE_NODE

Create

CreateDelayLine()

CreateItem()

CreateSample()

DefineSampleHere()

LoadSample()

LoadSampleHere()

ScanSample()

Delete

DeleteDelayLine()

DeleteItem()

UnloadSample()

Query

GetAudioItemInfo()

Modify

SetAudioItemInfo()

Use

AttachSample()

DebugSample()

Tags

Loading:

AF_TAG_NAME: (const char *) Create. Name of sample file to load.

AF_TAG_IMAGE_ADDRESS: (const char *) Create. Specifies a memory location containing a sample file image from which to read sample. Must use in conjunction with AF_TAG_IMAGE_LENGTH.

AF_TAG_IMAGE_LENGTH: (uint32) Create. Specifies number of bytes in sample file image pointed to by AF_TAG_IMAGE_ADDRESS.

AF_TAG_SCAN: (int32) Create. Specifies the maximum number of bytes of sound data to read from the file. This can be used to cause the Audio folio to simply load sample parameters without loading sample data.

AF_TAG_ALLOC_FUNCTION: (void *(*)(uint32 memsize, uint32 memflags)) Create. Sets custom memory allocation function to be called to allocate sample memory while loading sample file. Defaults to AllocMem(). If you supply a custom allocation function you must also provide a custom free function with AF_TAG_FREE_FUNCTION.

AF_TAG_FREE_FUNCTION: (void (*)(void *memptr, uint32 memsize)) Create. Sets custom memory free function to free sample memory to be called during sample deletion. Defaults to FreeMem(). If you supply a custom free function you must also provide a custom allocation function with AF_TAG_ALLOC_FUNCTION.

AF_TAG_LEAVE_IN_PLACE: (bool) When TRUE, causes sample being read from AF_TAG_IMAGE_ADDRESS to be used in-place instead of allocating more memory to hold the sample data. Mutually exclusive with AF_TAG_ALLOC_FUNCTION. See CreateSample() for more details and caveats.

Note that sample data may have to be moved down two bytes to align it properly for Opera DMA. This will destroy the sample image so that it cannot be reused.

AF_TAG_DATA_OFFSET: (uint32) Query. Byte offset in sample file of the beginning of the sample data.

AF_TAG_DATA_SIZE: (uint32) Query. Size of sample data in sample file in bytes. Note that this may differ from the length of the sample as loaded into memory (as returned by AF_TAG_NUMBYTES).

Data:

AF_TAG_ADDRESS: (void *) Create, Query, Modify. Address of sample data.

This tag, and the all the other Data tags, can be used to query or modify the data address/length of ordinary samples. They can only be used to query the address/length of a delay line.

AF_TAG_FRAMES: (uint32) Create, Query, Modify. Length of sample data expressed in frames. In a stereo sample, this would be the number of stereo pairs.

AF_TAG_NUMBYTES: (uint32) Create, Query, Modify. Length of sample data expressed in bytes.

Format:

AF_TAG_CHANNELS: (uint32) Create, Query, Modify. Number of channels (or samples per sample frame). For example: 1 for mono, 2 for stereo. Valid range is 1..255.

AF_TAG_WIDTH: (uint32) Create, Query, Modify. Number of bytes per sample (uncompressed). Valid range is 1..2.

AF_TAG_NUMBITS: (uint32) Create, Query, Modify. Number of bits per sample (uncompressed). Valid range is 1..32. Width is rounded up to the next byte when computed from this tag.

AF_TAG_COMPRESSIONTYPE: (uint32) Create, Query, Modify. 32-bit ID representing AIFC compression type of sample data (e.g. ID_SDX2). 0 for no compression.

AF_TAG_COMPRESSIONRATIO: (uint32) Create, Query, Modify. Compression ratio of sample data. Uncompressed data has a value of 1. 0 is illegal.

Loops:

AF_TAG_SUSTAINBEGIN: (int32) Create, Query, Modify. Frame index of the first frame of the sustain loop. Valid range is 0..NumFrames-1. -1 for no sustain loop. Use in conjunction with AF_TAG_SUSTAINEND.

AF_TAG_SUSTAINEND: (int32) Create, Query, Modify. Frame index of the first frame after the last frame in the sustain loop. Valid range is 1..NumFrames. -1 for no sustain loop. Use in conjunction with AF_TAG_SUSTAINBEGIN.

AF_TAG_RELEASEBEGIN: (int32) Create, Query, Modify. Frame index of the first frame of the release loop. Valid range is 0..NumFrames-1. -1 for no release loop. Use in conjunction with AF_TAG_RELEASEEND.

AF_TAG_RELEASEEND: (int32) Create, Query, Modify. Frame index of the first frame after the last frame in the release loop. Valid range is 1..NumFrames. -1 for no release loop. Use in conjunction with AF_TAG_RELEASEBEGIN.

Tuning:

AF_TAG_BASENOTE: (uint32) Create, Query, Modify. MIDI note number for this sample when played at the original sample rate (as set by AF_TAG_SAMPLE_RATE). Defaults to middle C (60). This defines the frequency conversion reference note for the StartInstrument() AF_TAG_PITCH tag.

AF_TAG_DETUNE: (int32) Create, Query, Modify. Amount to detune the MIDI base note in cents to reach the original pitch. Must be in the range of -100 to 100.

AF_TAG_SAMPLE_RATE: (ufrac16) Create, Query, Modify. Original sample rate for sample expressed in 16.16 fractional Hz. Defaults to 44,100 Hz.

AF_TAG_BASEFREQ: (ufrac16) Query. The frequency of the sample, expressed in 16.16 Hz, when played at the original sample rate. This value is computed from the other tuning tag values.

Multisample:

AF_TAG_LOWNOTE: (uint32) Create, Query, Modify. Lowest MIDI note number at which to play this sample when part of a multisample. StartInstrument() AF_TAG_PITCH tag is used to perform selection. Valid range is 0 to 127. Defaults to 0.

AF_TAG_HIGHNOTE: (uint32) Create, Query, Modify. Highest MIDI note number at which to play this sample when part of a multisample. Valid range is 0 to 127. Defaults to 127.

Notes

Sample creation tags have a lot mutual interaction. See CreateSample() for a complete explanation of this.

Caveats

There's currently no way to enforce that memory pointed to by AF_TAG_ADDRESS or file image memory used with AF_TAG_LEAVE_IN_PLACE is actually of MEMTYPE_AUDIO. Be careful.

All sample data, loop points, and lengths must be quad-byte aligned. For example, a 1-channel, 8-bit sample (which has 1 byte per frame) is only legal when the lengths and loop points are at multiples of 4 frames. For mono ADPCM samples (which have only 4 bits per frame), lengths and loop points must be at multiples of 8 frames. The Audio folio, however, does not report any kind of an error for using non-quad-byte aligned sample data. Sample addresses, lengths, and loop points, are internally truncated to quad-byte alignment when performing the DMA without warning. Misalignments may result in noise at loop points, or slight popping at the beginning and ending of sound playback. It is recommended that you pay very close attention to sample lengths and loop points when creating, converting, and compressing samples.

Setting AF_TAG_WIDTH does not set the AF_TAG_NUMBITS attribute (e.g. if you create a sample with AF_TAG_WIDTH set to 1, GetAudioItemInfo() AF_TAG_NUMBITS will return 16). Setting AF_TAG_NUMBITS does however correctly update the AF_TAG_WIDTH field.