The UMSAudioFile object is a base class. Specific audio file implementations inherit their interface from this class. Objects, such as the UMSAudioPlayer, and applications can achieve audio file-type independence by accessing audio file data through the methods of the base class. This allows the application to transparently support any audio file types for which a UMSAudioFile object is provided without knowing the specific object implementation being used.
A metaclass is provided with a method to construct a specific audio file based on a user specified path name to an audio file, a Detector alias, and data in the configuration file. The construction method in the metaclass invokes the series of detectors specified by the Detector alias. If the file type is recognized by one of the detectors, the corresponding specific audio file object is instantiated and returned. This allows applications to be extended to support new audio file types by adding new audio file objects and corresponding detectors.
Note that this is the preferred construction technique for applications. Alternatively, a specific audio file object can be constructed using the ObjectNameNew method.
The object presents the paradigm that the file consists of a length of audio data. The file position can be set by seeking to an offset within the data where the offset is specified as bytes, samples, or milliseconds. Specific implementations may have an underlying structure that allows storing of attributes, such as sample rate and format. These implementations respond with True to the has_attributes query. Implementations that have attributes initialize the object attributes based on data that is in an existing file or save the attribute settings to files that are being created.
To learn more about the UMSAudioFile object, see:
For introductory information, see Formatted File Access Objects.
To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list may vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are listed as follows:
enum ReturnCode {
Success,
Failure,
InvalidTimeFormat,
FormatChange,
EndOfFile,
UnsupportedFormat,
MemoryError,
OutOfRange,
InsufficientBufferLength,
};
The UMSAudioFile object also uses the following enumerated list defined in UMSAudioTypes.idl.
enum TimeFormat {
Msecs,
Bytes,
Samples
};
This method opens a file. If the file does not exist and the proper oflags are specified then the file will be created. If the file exists then it is opened. If the specific file implementation supports storage of audio parameters, the objects audio parameters are initialized based on the contents of the file. The file position is set to the beginning of the audio data. The preferred method of opening existing files is via the metaclass make_by_pathname method which constructs the specific UMSAudioFile object and returns the object with the file opened. The preferred method of opening a new file is to construct the specific object using the metaclass make_by_alias method and then use the open method with appropriate flags to create the file.
Success Failure
All data and headers are written to the file and the file is closed.
Success Failure
This method checks the status of the last file operation. If the operation was successful, then Success is returned, otherwise, Failure is returned.
Success Failure
This method seeks to a location specified by position. The position is interpreted based on the value of the tformat parameter to be Msecs, Bytes, or Samples. The seek position is relative to the start of the audio data in the file.
| in long position | The requested seek position in units of the specified time format. |
| in UMSAudioTypes::TimeFormat tformat | The specified time units of Msecs, Bytes, or Samples. |
Success Failure InvalidTimeFormat OutOfRange
The current file position is returned in the position parameter in the time units specified by the tformat parameter.
| in UMSAudioTypes::TimeFormat tformat | The specified time units of Msecs, Bytes, or Samples. |
| inout long pos | The requested seek position in units of the specified time format. |
Success Failure InvalidTimeFormat
The file length is returned in the length parameter in the time units specified by the tformat parameter. Length is presented as the length of audio data contained in the file.
| in UMSAudioTypes::TimeFormat tformat | The specified time units of Msecs, Bytes, or Samples. |
| inout long length | The file length in units of the specified time format. |
Success Failure InvalidTimeFormat
This method returns audio data in the buffer sequence provided. The data returned is from the current file position and of the length reported in the samples_read parameter. The samples_requested parameter input specifies the desired number of samples to read. The length is specified in samples to enforce sample bounded access to the data. If an end of file condition occurs prior to the requested samples being read, the read is terminated, a ReturnCode value of EndOfFile is returned, and samples_read is set to the actual number of samples returned. For stereo data a sample includes the data for both the left and right channel. The current file position is advanced by the number of samples read. A file object can support midstream format changes by returning data up to the format change and setting ReturnCode to FormatChange. No further data should be returned until the application queries the changed attributes.
Success Failure InsufficientBufferLength FormatChange EndOfFile
This method writes the audio data provided in the buffer to the file. The data written is inserted at the current file position and of the length reported in the samples_written parameter. The samples_to_write parameter specifies the desired number of samples to write. The length is specified in samples to enforce sample bounded access to the data. For stereo data a sample includes the data for both the left and right channel. The current file position is advanced by the number of samples written.
Success Failure MemoryError
The filetype alias is returned as a string. The specific UMSAudioDevice class should be registered under this alias in the configuration file.
| out string file_alias | A string containing the filetype alias. |
Success Failure MemoryError
Specific UMSAudioFile implementations may or may not support storage of audio attributes in the file format. This method is provided to query whether the object supports attribute storage.
| inout boolean attributes | Returned with a TRUE value if attributes are supported. |
Success Failure
This method allows the user to specify the byte order for data received on read or supplied on write. The format that the data is actually stored in the file may be different than this. For example, by convention WAVE files always use MSB byte order and SND files always use LSB order. In these cases a user specified byte order that conflicts with the file standard simply causes the data to/from the user to be converted.
| in string byte_order | A string specifying the desired byte order. Supported values are MSB and LSB for Big Endian and Little Endian respectively. |
Success Failure
The current setting of byte order is returned.
| out string byte_order | string specifying the desired byte order. Supported values are MSB and LSB for Big Endian and Little Endian respectively. |
Success Failure
This method sets the number format to the value specified by the number_format_string parameter. If this is different than data in the file a ReturnCode value of UnsupportedFormat is returned. It is a convention to use signed for 8-bit data and twos complement for 16-bit data.
| in string nfs | A string specifying the number format for the audio data. Possible values are unsigned, signed, and twos complement. |
Success Failure UnsupportedFormat MemoryError
This method returns a string indicating the current number format for audio data.
| out string number_format | A string specifying the number format for the audio data. Possible values are unsigned, signed and twos complement. |
Success Failure MemoryError
This method sets the audio format to the value specified by the audio_format_string parameter. If this is different than data in the file a ReturnCode value of UnsupportedFormat is returned. Possible values for WAV and SND audio file objects are PCM, A-law, and mu-law. The list of file formats supported by a file object is contained in the configuration file under the audio_formats_alias for the file object. This method selects the audio format to use by specifying one of the properties of the audio_formats_alias.
| in string afs | A string specifying the audio format for the audio data. |
Success Failure UnsupportedFormat MemoryError
This method returns a string indicating the current format for audio data. Possible values for WAV and SND audio file objects are PCM, A-law, and mu-law. The list of file formats supported by a file object is contained in the configuration file under the audio_formats_alias for the file object.
| out string format | A string specifying the number format for the audio data. |
Success Failure MemoryError
The method sets the sample rate for audio data. This overrides an attribute value extracted from the file. If the setting is different than the file data, the file may be corrupted at close. In general, this method should not be used on file objects that support attributes unless the file is being created.
| in long sps | The specified sample rate in samples per second. |
Success Failure
The current sample rate is returned in the samples_per_second parameter.
| inout long sps | The current sample rate in samples per second. |
Success Failure
The method sets the bits per sample attribute for audio data. This overrides an attribute value extracted from the file. Since the object provides file creation/modification capability the setting specified should match the data content of the file. In general, this method should not be used on file objects that support attributes unless the file is being created.
| in long bps | The specified bits per sample attribute for audio data. |
Success Failure
The number of bits per sample of audio data is returned in the bits_per_sample parameter. Even though sample boundaries for stereo data includes data for the left and right channel, the number of bits per sample reports the bits in only 1 channel (for example, 8-bit mu-law data is 8 bits per sample regardless of whether it is mono or stereo).
| inout long bps | The number of bits per sample of audio data. |
Success Failure
The method sets the number of channels for audio data. This overrides an attribute value extracted from the file. If the setting is different than the file data, the file may be corrupted at close. In general, this method should not be used on file objects that support attributes unless the file is being created.
| in long chan | The specified value for the number of channels attribute for audio data. |
Success Failure
The value of the number of channels attribute is returned.
| inout long chan | The current channels value for the audio data is returned. |
Success Failure
For introductory information, see Formatted File Access Objects.