<CoreAudioTypes/CoreAudioBaseTypes.h>, <AudioToolbox/AudioFile.h> メモ
<CoreAudioTypes/CoreAudioBaseTypes.h>, <AudioToolbox/AudioFile.h> 内に記載されている説明のコピぺー。
AudioStreamBasicDescription
This structure encapsulates all the information for describing the basic format properties of a stream of audio data.
This structure is sufficient to describe any constant bit rate format that has channels that are the same size. Extensions are required for variable bit rate data and for constant bit rate data where the channels have unequal sizes. However, where applicable, the appropriate fields will be filled out correctly for these kinds of formats (the extra data is provided via separate properties). In all fields, a value of 0 indicates that the field is either unknown, not applicable or otherwise is inapproprate for the format and should be ignored. Note that 0 is still a valid value for most formats in the mFormatFlags field.
In audio data a frame is one sample across all channels. In non-interleaved audio, the per frame fields identify one channel. In interleaved audio, the per frame fields identify the set of n channels. In uncompressed audio, a Packet is one frame, (mFramesPerPacket == 1). In compressed audio, a Packet is an indivisible chunk of compressed data, for example an AAC packet will contain 1024 sample frames.
struct AudioStreamBasicDescription
{
Float64 mSampleRate;
AudioFormatID mFormatID;
AudioFormatFlags mFormatFlags;
UInt32 mBytesPerPacket;
UInt32 mFramesPerPacket;
UInt32 mBytesPerFrame;
UInt32 mChannelsPerFrame;
UInt32 mBitsPerChannel;
UInt32 mReserved;
}
| var | Description |
|---|---|
| mSampleRate | The number of sample frames per second of the data in the stream. |
| mFormatID | The AudioFormatID indicating the general kind of data in the stream. |
| mFormatFlags | The AudioFormatFlags for the format indicated by mFormatID. |
| mBytesPerPacket | The number of bytes in a packet of data. |
| mFramesPerPacket | The number of sample frames in each packet of data. |
| mBytesPerFrame | The number of bytes in a single sample frame of data. |
| mChannelsPerFrame | The number of channels in each frame of data. |
| mBitsPerChannel | The number of bits of sample data for each channel in a frame of data. |
| mReserved | Pads the structure out to force an even 8 byte alignment. |
Audio File Properties
Constants for AudioFile get/set property calls.
| AudioFilePropertyID | Description |
|---|---|
| kAudioFilePropertyFileFormat | An AudioFileTypeID that identifies the format of the file |
| kAudioFilePropertyDataFormat | An AudioStreamBasicDescription describing the format of the audio data |
| kAudioFilePropertyFormatList | In order to support formats such as AAC SBR where an encoded data stream can be decoded to multiple destination formats, this property returns an array of AudioFormatListItems (see AudioFormat.h) of those formats. The default behavior is to return an AudioFormatListItem that has the same AudioStreamBasicDescription that kAudioFilePropertyDataFormat returns. |
| kAudioFilePropertyIsOptimized | A UInt32 indicating whether an Audio File has been optimized. Optimized means it is ready to start having sound data written to it. A value of 0 indicates the file needs to be optimized. A value of 1 indicates the file is currently optimized. |
| kAudioFilePropertyMagicCookieData | A void * pointing to memory set up by the caller. Some file types require that a magic cookie be provided before packets can be written to the file, so this property should be set before calling AudioFileWriteBytes()/AudioFileWritePackets() if a magic cookie exists. |
| kAudioFilePropertyAudioDataByteCount | a UInt64 that indicates the number of bytes of audio data contained in the file |
| kAudioFilePropertyAudioDataPacketCount | a UInt64 that indicates the number of packets of audio data contained in the file |
| kAudioFilePropertyMaximumPacketSize | a UInt32 that indicates the maximum size of a packet for the data contained in the file |
| kAudioFilePropertyDataOffset | a SInt64 that indicates the byte offset in the file of the audio data. |
| kAudioFilePropertyChannelLayout | An AudioChannelLayout struct. |
| kAudioFilePropertyDeferSizeUpdates | A UInt32. If 1, then updating the files sizes in the header is not done for every write, but deferred until the file is read, optimized or closed. This is more efficient, but less safe since, if the application crashes before the size is updated, the file may not be readable. The default value is one, it doesn't update the header. |
| kAudioFilePropertyDataFormatName | This is deprecated Use kAudioFormatProperty_FormatName in AudioFormat.h instead. |
| kAudioFilePropertyMarkerList | access the list of markers defined in the file. returns an AudioFileMarkerList. The CFStringRefs in the returned structs must be released by the client. available in 10.2.4 and later |
| kAudioFilePropertyRegionList | access the list of regions defined in the file. returns an Array of AudioFileRegions. The CFStringRefs in the returned structs must be released by the client. available in 10.2.4 and later |
| kAudioFilePropertyPacketToFrame | pass a AudioFramePacketTranslation with mPacket filled out and get mFrame back. mFrameOffsetInPacket is ignored. |
| kAudioFilePropertyFrameToPacket | pass a AudioFramePacketTranslation with mFrame filled out and get mPacket and mFrameOffsetInPacket back. |
| kAudioFilePropertyRestrictsRandomAccess | A UInt32 indicating whether an Audio File contains packets that cannot be used as random access points. A value of 0 indicates that any packet can be used as a random access point, i.e. that a decoder can start decoding with any packet. A value of 1 indicates that some packets cannot be used as random access points, i.e. that kAudioFilePropertyPacketToRollDistance must be employed in order to identify an appropriate initial packet for decoding. |
| kAudioFilePropertyPacketToRollDistance | Pass an AudioPacketRollDistanceTranslation with mPacket filled out and get mRollDistance back. The roll distance indicates the count of packets that must be decoded prior to the packet with the specified number in order to achieve the best practice for the decoding of that packet. For file types for which a minimal roll distance is prohibitively expensive to determine per packet, the value returned may be derived from an upper bound for all packet roll distances. If the value of kAudioFilePropertyRestrictsRandomAccess is 1, either kAudioFilePropertyPacketToRollDistance or kAudioFilePropertyPacketToDependencyInfo must be used in order to identify an appropriate random access point. If the value of kAudioFilePropertyRestrictsRandomAccess is 0, kAudioFilePropertyPacketToRollDistance can be used in order to identify the best available random access point, which may be prior to the specified packet even if the specified packet can be used as a random access point. |
| kAudioFilePropertyPreviousIndependentPacket kAudioFilePropertyNextIndependentPacket |
Pass an AudioIndependentPacketTranslation with mPacket filled out and get mIndependentlyDecodablePacket back. A value of -1 means that no independent packet is present in the stream in the direction of interest. Otherwise, for kAudioFilePropertyPreviousIndependentPacket, mIndependentlyDecodablePacket will be less than mPacket, and for kAudioFilePropertyNextIndependentPacket, mIndependentlyDecodablePacket will be greater than mPacket. |
| kAudioFilePropertyPacketToDependencyInfo | Pass an AudioPacketDependencyInfoTranslation with mPacket filled out and get mIsIndependentlyDecodable and mPrerollPacketCount back. A value of 0 for mIsIndependentlyDecodable indicates that the specified packet is not independently decodable. A value of 1 for mIsIndependentlyDecodable indicates that the specified packet is independently decodable. For independently decodable packets, mPrerollPacketCount indicates the count of packets that must be decoded after the packet with the specified number in order to refresh the decoder. If the value of kAudioFilePropertyRestrictsRandomAccess is 1, either kAudioFilePropertyPacketToRollDistance or kAudioFilePropertyPacketToDependencyInfo must be used in order to identify an appropriate random access point. |
| kAudioFilePropertyPacketToByte | pass an AudioBytePacketTranslation struct with mPacket filled out and get mByte back. mByteOffsetInPacket is ignored. If the mByte value is an estimate then kBytePacketTranslationFlag_IsEstimate will be set in the mFlags field. |
| kAudioFilePropertyByteToPacket | pass an AudioBytePacketTranslation struct with mByte filled out and get mPacket and mByteOffsetInPacket back. If the mPacket value is an estimate then kBytePacketTranslationFlag_IsEstimate will be set in the mFlags field. |
| kAudioFilePropertyChunkIDs | returns an array of OSType four char codes for each kind of chunk in the file. |
| kAudioFilePropertyInfoDictionary | returns a CFDictionary filled with information about the data contained in the file. See dictionary key constants already defined for info string types. AudioFileComponents are free to add keys to the dictionaries that they return for this property... caller is responsible for releasing the CFObject |
| kAudioFilePropertyPacketTableInfo | Gets or sets an AudioFilePacketTableInfo struct for the file types that support it. When setting, the sum of mNumberValidFrames, mPrimingFrames and mRemainderFrames must be the same as the total number of frames in all packets. If not you will get a kAudio_ParamError. The best way to ensure this is to get the value of the property and make sure the sum of the three values you set has the same sum as the three values you got. |
| kAudioFilePropertyPacketSizeUpperBound | a UInt32 for the theoretical maximum packet size in the file (without actually scanning the whole file to find the largest packet, as may happen with kAudioFilePropertyMaximumPacketSize). |
| kAudioFilePropertyPacketRangeByteCountUpperBound | Pass an AudioPacketRangeByteCountTranslation with mPacket and mPacketCount filled out and get mByteCountUpperBound back. The value of mByteCountUpperBound can be used to allocate a buffer for use with AudioFileReadPacketData in order to accommodate the entire packet range. May require scanning in order to obtain the requested information, but even if so, no scanning will occur beyond the last packet in the specified range. For file formats in which packets are directly accessible and stored both contiguously and byte-aligned, the returned upper bound will be equal to the total size of the packets in the range. Otherwise the upper bound may reflect per-packet storage overhead. |
| kAudioFilePropertyReserveDuration | The value is a Float64 of the duration in seconds of data that is expected to be written. Setting this property before any data has been written reserves space in the file header for a packet table and/or other information so that it can appear before the audio data. Otherwise the packet table may get written at the end of the file, preventing the file from being streamable. |
| kAudioFilePropertyEstimatedDuration | The value is a Float64 representing an estimated duration in seconds. If duration can be calculated without scanning the entire file, or all the audio data packets have been scanned, the value will accurately reflect the duration of the audio data. |
| kAudioFilePropertyBitRate | Returns the bit rate for the audio data as a UInt32. For some formats this will be approximate. |
| kAudioFilePropertyID3Tag | A void * pointing to memory set up by the caller to contain a fully formatted ID3 tag (get/set v2.2, v2.3, or v2.4, v1 get only). The ID3 tag is not manipulated in anyway either for read or write. When setting, this property must be called before calling AudioFileWritePackets. |
| kAudioFilePropertySourceBitDepth | For encoded data this property returns the bit depth of the source as an SInt32, if known. The bit depth is expressed as a negative number if the source was floating point, e.g. -32 for float, -64 for double. |
| kAudioFilePropertyAlbumArtwork | returns a CFDataRef filled with the Album Art or NULL. The caller is responsible for releasing a non-NULL CFDataRef. In order to parse the contents of the data, CGImageSourceCreateWithData may be used. |
| kAudioFilePropertyAudioTrackCount | a UInt32 that indicates the number of audio tracks contained in the file. (get property only) |
| kAudioFilePropertyUseAudioTrack | a UInt32 that indicates the number of audio tracks contained in the file. (set property only) |
AudioFile error codes
These are the error codes returned from the AudioFile API.
| Error Code | Description | Four char code | OSStatus Code | Remarks |
|---|---|---|---|---|
| kAudioFileUnspecifiedError | An unspecified error has occurred. | wht? | 2003334207 | |
| kAudioFileUnsupportedFileTypeError | The file type is not supported. | typ? | 1954115647 | |
| kAudioFileUnsupportedDataFormatError | The data format is not supported by this file type. | fmt? | 1718449215 | |
| kAudioFileUnsupportedPropertyError | The property is not supported. | pty? | 1886681407 | |
| kAudioFileBadPropertySizeError | The size of the property data was not correct. | !siz | 561211770 | |
| kAudioFilePermissionsError | The operation violated the file permissions. For example, trying to write to a file opened with kAudioFileReadPermission. | prm? | 1886547263 | |
| kAudioFileNotOptimizedError | There are chunks following the audio data chunk that prevent extending the audio data chunk. The file must be optimized in order to write more audio data. |
optm | 1869640813 | |
| kAudioFileInvalidChunkError | The chunk does not exist in the file or is not supported by the file. | chk? | 1667787583 | |
| kAudioFileDoesNotAllow64BitDataSizeError | The a file offset was too large for the file type. AIFF and WAVE have a 32 bit file size limit. | off? | 1868981823 | |
| kAudioFileInvalidPacketOffsetError | A packet offset was past the end of the file, or not at the end of the file when writing a VBR format, or a corrupt packet size was read when building the packet table. | pck? | 1885563711 | |
| kAudioFileInvalidPacketDependencyError | Either the packet dependency info that's necessary for the audio format has not been provided, or the provided packet dependency info indicates dependency on a packet that's unavailable. | dep? | 1684369471 | |
| kAudioFileInvalidFileError | The file is malformed, or otherwise not a valid instance of an audio file of its type. | dta? | 1685348671 | |
| kAudioFileOperationNotSupportedError | The operation cannot be performed. For example, setting kAudioFilePropertyAudioDataByteCount to increase the size of the audio data in a file is not a supported operation. Write the data instead. | 1869627199 | 'op??', integer used because of trigraph | |
| kAudioFileNotOpenError | The file is closed. | -38 | ||
| kAudioFileEndOfFileError | End of file. | -39 | ||
| kAudioFilePositionError | Invalid file position. | -40 | ||
| kAudioFileFileNotFoundError | File not found. | -43 |
