Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 7 - Sound / Sound Reference

Data Structures

Sound Frame

A sound frame has the following slots.

Note

You can use the new proto, *protoSoundFrame (page 7-44), as the basis for sound frames in the 2.1 OS. Using this proto provides enhanced features through methods that it includes.

Slot descriptions

sndFrameType

Required. A symbol specifying the type of the sound frame. The 'simpleSound symbol indicates a standard sound, while the 'codec symbol indicates a sound compressed with a codec. For information on codecs, see "Compressing Sound". If you specify the symbol 'codec, you must also supply the codecName, bufferCount, and bufferSize slots.

codecName

A string identifying the codec to be used to compress or decompress the sound. This slot is required if you specify 'codec in the sndFrameType slot. For more details on the possible string values, see Table 7-4 (page 7-27).

bufferCount

An integer specifying the number of codec buffers to allocate. Each buffer has the size specified in the bufferSize slot. This slot is required if you specify 'codec for the sndFrameType slot. For guidelines on this value, see "Using Codecs to Compress and Decompress Sound".

bufferSize

An integer specifying the size of each codec buffer in bytes. This slot is required if you specify 'codec for the sndFrameType slot. For guidelines on this value, see "Using Codecs to Compress and Decompress Sound".

samples

Required. A binary object of the class 'samples, that contains the sound samples. If the synthesizer codec is being used, this slot contains the synthesizer data, which is a binary object of the class 'TDTMFCodec.

samplingRate

Optional. Real or integer value describing the sampling rate of the data in the samples slot. (8000.0, 11013.21586, and 22026.43172 are common values). If missing, the sound channel assumes 22026.43172. When using a codec, this value also describes the sampling rate of data in the codec buffers.

compressionType

Optional. An integer identifying the encoding format of the samples. If present, it must be kSampleStandard (0), kSampleLinear (6), or kSampleMuLaw (1). If missing, kSampleStandard is assumed. If you specify kSampleMuLaw (or kSampleStandard), you must also set the dataType slot to k8Bit, since this compressor reduces 16-bit samples to 8-bit samples. If you specify kSampleLinear, you must also set the dataType slot to k16bit. For more details on the formats, see Table 7-5 (page 7-27).

compressionRatio

Optional. A ratio of the number of uncompressed sound samples (not bytes) per a number of compressed bytes. For example, for IMA compression, you would specify 64/34, because 64 samples are compressed into 34 bytes. This value is used to update the user interface progress indicator while a compressed sound is playing or recording.

dataType

Optional. An integer specifying the size of each sample in bits. If present, it must be k8Bit (8) or k16Bit (16). If missing, k8Bit is assumed.

Note

Older versions of NTK generate sound frames having the value 0 (zero) in the dataType slot. The system assumes 0 (zero) is the same as 8 (k8Bit).

volume

Optional. An integer or real value specifying the volume level at which to play this sound. If missing, the channel's volume setting (see *SetVolume method) is used. Note that if volume is an integer it must have the value 0, 1, 2, 3, or 4 corresponding to decibel levels silent, -18 dB, -6 dB, -3 dB, or 0 dB (unity gain) respectively. If volume is a real number, it is treated as the actual dB level, and must be negative.

This value overrides the system volume and the channel volume--including values set by functions such as PlaySoundAtVolume and sound channel methods such as *SetVolume.

start

Optional. An integer value that is the index of the first sample to play. When this value is missing, 0 is assumed. Omit this slot in sound frames used for recording.

count

Optional. An integer specifying the number of samples to play. When this value is missing, Length(samples) / (dataType/8) is assumed. Omit this slot in sound frames used for recording.

loops

Optional. An integer that is the number of times to repeat the sound. For example, setting loops to 3 causes the sound to play a total of four times. When this value is missing, 0 is assumed. There is no way to specify continuous play. Omit this slot in sound frames used for recording.

The following *Callback method is also part of the sound frame.

© Apple Computer, Inc.
26 APR 1997

Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help