view toolboxes/MIRtoolbox1.3.2/MIRToolbox/aiffread.m @ 0:e9a9cd732c1e tip

first hg version after svn

function [data,Fs,nBits,formChunk] = aiffread(filePath,indexRange)
%AIFFREAD   Read AIFF (Audio Interchange File Format) sound file.
%   Y = AIFFREAD(FILE) reads an AIFF file specified by the string FILE,
%   returning the sampled data in Y. The ".aif" extension is appended if no
%   extension is given.
%
%   [Y,FS,NBITS,CHUNKDATA] = AIFFREAD(FILE) returns the sample rate (FS) in
%   Hertz, the number of bits per sample (NBITS) used to encode the data in
%   the file, and a complete structure of the chunk data (CHUNKDATA)
%   contained in the AIFF file (minus the actual audio data returned in Y).
%   See below for a description of CHUNKDATA.
%
%   [...] = AIFFREAD(FILE,N) returns only the first N samples from each
%   channel in the file.
%
%   [...] = AIFFREAD(FILE,[N1 N2]) returns only samples N1 through N2 from
%   each channel in the file.
%
%   [SIZ,...] = AIFFREAD(FILE,'size') returns the size of the audio data
%   contained in the file in place of the actual audio data, where
%   SIZ = [nSampleFrames nChannels].
%
%-NOTES--------------------------------------------------------------------
%
%   A note on compressed files:
%
%      Both AIFF and AIFC/AIFF-C (compressed) file types can be read by
%      AIFFREAD, but the data returned for AIFC/AIFF-C files will be the
%      raw, compressed data (i.e. AIFFREAD loads the data from the file
%      without modification). Currently, since there are many compression
%      formats, it is the responsibility of the user to uncompress the
%      sound data using parameters defined in the COMM chunk (contained in
%      the returned CHUNKDATA structure). When loading AIFC/AIFF-C files,
%      any optional numerical subranges are ignored and the entire set of
%      compressed data is returned as a column vector of signed bytes
%      (INT8 type).
%
%   A note on the CHUNKDATA structure:
%
%      The CHUNKDATA structure has the following fields:
%
%         -'chunkID': The 4-character ID for the chunk. This will always be
%                     the string 'FORM'.
%         -'chunkSize': The size (in bytes) of the remaining data in the
%                       file.
%         -'formType': A 4-character string for the file type that should
%                      be either 'AIFF' or 'AIFC'.
%         -'chunkArray': An array of structures, one entry for every chunk
%                        that is in the file (not counting this parent FORM
%                        chunk). The fields of this structure are:
%                           -'chunkID': The 4-character ID for the chunk.
%                           -'chunkSize': The size (in bytes) of the
%                                         remaining data in the chunk.
%                           -'chunkData': A structure of data for the
%                                         chunk. The form of this data for
%                                         a given chunkID can be found at
%                                         the links given below for the
%                                         file format standards.
%
%      The data portion of certain chunks may not have a clearly defined
%      format, or that format may be dependent on the implementation or
%      application that will be using the data. In such cases, the data
%      returned for that chunk in the CHUNKDATA structure will be in a raw
%      format (vectors of signed or unsigned 8-bit integers) and it will be
%      up to the user/application to parse and format this data correctly.
%      The following is a list of such AIFF/AIFF-C chunks:
%
%         -Audio Recording Chunk (chunkID = 'AESD'): The chunkData
%          structure has one field 'aesChannelStatusData' that stores a
%          column vector of 24 8-bit unsigned integers.
%         -Application Specific Chunk (chunkID = 'APPL'): The chunkData
%          structure has two fields. 'applicationSignature' stores a
%          4-character string identifying the application. 'data' stores a
%          column vector of 8-bit signed integers.
%         -MIDI Data Chunk (chunkID = 'MIDI'): The chunkData structure has
%          one field 'midiData' that stores a column vector of 8-bit
%          unsigned integers.
%         -Sound Accelerator (SAXEL) Chunk (chunkID = 'SAXL'): There is no
%          finalized format for Saxel chunks, so the chunkData structure
%          follows the draft format given in Appendix D of the AIFF-C
%          standard.
%
%   Description for the AIFF standard can be found here:
%
%      http://muratnkonar.com/aiff/index.html
%
%   Descriptions for the AIFC/AIFF-C standard can be found here:
%
%      http://www.cnpbagwell.com/aiff-c.txt
%      http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/AIFF/Docs/...
%             AIFF-C.9.26.91.pdf

% Author: Ken Eaton
% Last modified: 3/17/09
%--------------------------------------------------------------------------

  % Initializations:

  aiffChunkPrecedence = {'COMM' 'SSND' 'MARK' 'INST' 'COMT' 'NAME' ...
                         'AUTH' '[c] ' 'ANNO' 'AESD' 'MIDI' 'APPL'};
  aiffChunkLimits = [1 1 1 1 1 1 1 1 inf 1 inf inf];
  aifcChunkPrecedence = {'FVER' 'COMM' 'INST' 'SAXL' 'COMT' 'MARK' ...
                         'SSND' 'NAME' 'AUTH' '[c] ' 'ANNO' 'AESD' ...
                         'MIDI' 'APPL'};
  aifcChunkLimits = [1 1 1 inf 1 1 1 1 1 1 inf 1 inf inf];
  fid = -1;

  % Check the number of input arguments:

  switch nargin,
    case 0,
      error(error_message('notEnoughInputs'));
    case 1,
      indexRange = [1 inf];
  end

  % Check the file name input argument:

  if ~ischar(filePath),
    error(error_message('badArgumentType','File name','char'));
  end
  [filePath,fileName,fileExtension] = fileparts(filePath);
  if isempty(fileExtension),
    fileExtension = '.aif';
  end
  if ~any(strcmpi(fileExtension,{'.aif' '.afc' '.aiff' '.aifc'})),
    error(error_message('unknownExtension',fileExtension));
  end

  % Check the optional input argument:

  if isnumeric(indexRange),  % Numeric range specification

    indexRange = double(indexRange);
    nRange = numel(indexRange);
    if (nRange > 2) || any(indexRange < 1) || any(isnan(indexRange)),
      error(error_message('badIndexValue'));
    end
    indexRange = [ones(nRange ~= 2) round(indexRange) inf(nRange == 0)];

  elseif ischar(indexRange),  % Specification for returning just the size

    if ~strncmpi(indexRange,'size',numel(indexRange)),
      error(error_message('invalidString'));
    end
    indexRange = [];

  else  % Invalid input

    error(error_message('badArgumentType','Optional argument',...
                        'numeric or char'));

  end

  % Check that the file exists and can be opened:

  fid = fopen(fullfile(filePath,[fileName fileExtension]),'r','b');
  if fid == -1,
    error(error_message('invalidFile',[fileName fileExtension]));
  end

  % Initialize formChunk structure:

  formChunk = struct('chunkID',[],'chunkSize',[],'formType',[],...
                     'chunkArray',[]);

  % Read FORM chunk data:

  formChunk.chunkID = read_text(fid,4);
  if ~strcmp(formChunk.chunkID,'FORM'),
    error(error_message('invalidFileFormat',fileExtension));
  end
  formChunk.chunkSize = fread(fid,1,'int32');
  formType = read_text(fid,4);
  if ~any(strcmp(formType,{'AIFF' 'AIFC'})),
    error(error_message('invalidFileFormat',fileExtension));
  end
  formChunk.formType = formType;

  % Since the order of chunks is not guaranteed, first skip through the
  %   file and read just the chunkIDs and chunkSizes:

  iChunk = 0;
  chunkIDArray = {};
  chunkSizeArray = {};
  chunkDataIndex = [];
  nextChunkID = read_text(fid,4);
  while ~feof(fid),
    iChunk = iChunk+1;
    chunkIDArray{iChunk} = nextChunkID;
    chunkSize = fread(fid,1,'int32');
    chunkSizeArray{iChunk} = chunkSize;
    chunkDataIndex(iChunk) = ftell(fid);
    fseek(fid,chunkSize+rem(chunkSize,2),'cof');
    nextChunkID = read_text(fid,4);
  end

  % Check for the presence of required chunks:

  if ~ismember('COMM',chunkIDArray),
    error(error_message('missingChunk','COMM',formType));
  end
  if strcmp(formType,'AIFC') && ~ismember('FVER',chunkIDArray),
    error(error_message('missingChunk','FVER',formType));
  end

  % Check for unknown chunks and order chunks based on chunk precedence:

  if strcmp(formType,'AIFF'),
    [isChunk,orderIndex] = ismember(chunkIDArray,aiffChunkPrecedence);
  else
    [isChunk,orderIndex] = ismember(chunkIDArray,aifcChunkPrecedence);
  end
  if ~all(isChunk),
    unknownChunks = [chunkIDArray(~isChunk); ...
                     repmat({', '},1,sum(~isChunk)-1) {'.'}];
    orderIndex = orderIndex(isChunk);
    chunkIDArray = chunkIDArray(isChunk);
    chunkSizeArray = chunkSizeArray(isChunk);
    chunkDataIndex = chunkDataIndex(isChunk);
    warning('aiffread:unknownChunk',...
            ['The following chunk IDs are unknown for an ' formType ...
             ' file and will be ignored: ' unknownChunks{:}]);
  end
  [index,orderIndex] = sort(orderIndex);
  chunkIDArray = chunkIDArray(orderIndex);
  chunkSizeArray = chunkSizeArray(orderIndex);
  chunkDataIndex = chunkDataIndex(orderIndex);

  % Check for chunks that should not appear more than once:

  index = unique(index(diff(index) < 1));
  if strcmp(formType,'AIFF'),
    repeatChunks = aiffChunkPrecedence(aiffChunkLimits(index) == 1);
  else
    repeatChunks = aifcChunkPrecedence(aifcChunkLimits(index) == 1);
  end
  if ~isempty(repeatChunks),
    repeatChunks = [repeatChunks; ...
                    repmat({', '},1,numel(repeatChunks)-1) {'.'}];
    error(error_message('repeatChunk',formType,[repeatChunks{:}]));
  end

  % Initialize chunkArray data:

  formChunk.chunkArray = struct('chunkID',chunkIDArray,...
                                'chunkSize',chunkSizeArray,...
                                'chunkData',[]);

  % Read the data for each chunk:

  for iChunk = 1:numel(chunkIDArray),
    chunkData = [];
    fseek(fid,chunkDataIndex(iChunk),'bof');
    switch chunkIDArray{iChunk},

      case '[c] ',  % Copyright Chunk

        chunkData.text = read_text(fid,chunkSizeArray{iChunk});

      case 'AESD',  % Audio Recording Chunk

        chunkData.aesChannelStatusData = ...
          fread(fid,[chunkSizeArray{iChunk} 1],'*uint8');

      case 'ANNO',  % Annotation Chunk

        chunkData.text = read_text(fid,chunkSizeArray{iChunk});

      case 'APPL',  % Application Specific Chunk

        chunkData.applicationSignature = read_text(fid,4);
        chunkData.data = fread(fid,[chunkSizeArray{iChunk}-4 1],'*int8');

      case 'AUTH',  % Author Chunk

        chunkData.text = read_text(fid,chunkSizeArray{iChunk});

      case 'COMM',  % Common Chunk

        nChannels = fread(fid,1,'int16');
        chunkData.nChannels = nChannels;
        nSampleFrames = fread(fid,1,'uint32');
        if (nSampleFrames > 0) && ~ismember('SSND',chunkIDArray),
          error(error_message('missingChunk','SSND',formType));
        end
        chunkData.nSampleFrames = nSampleFrames;
        nBits = fread(fid,1,'int16');
        chunkData.sampleSize = nBits;
        exponent = fread(fid,1,'uint16');
        highMantissa = fread(fid,1,'uint32');
        lowMantissa = fread(fid,1,'uint32');
        Fs = extended2double(exponent,highMantissa,lowMantissa);
        chunkData.sampleRate = Fs;
        if strcmp(formType,'AIFF'),
          compressionType = 'NONE';
        else
          compressionType = read_text(fid,4);
          chunkData.compressionType = compressionType;
          chunkData.compressionName = read_pstring(fid);
        end

      case 'COMT',  % Comments Chunk

        nComments = fread(fid,1,'uint16');
        chunkData.nComments = nComments;
        chunkData.commentArray = struct('timeStamp',cell(nComments,1),...
                                        'marker',[],'count',[],'text',[]);
        for iComment = 1:nComments,
          chunkData.commentArray(iComment) = read_comment(fid);
        end

      case 'FVER',  % Format Version Chunk (AIFC/AIFF-C only)

        timeStamp = fread(fid,1,'uint32');
        if timeStamp ~= 2726318400,
          warning('aiffread:unknownVersion',...
                  ['File contains an unrecognized version of the ' ...
                   'AIFC/AIFF-C standard.']);
        end
        chunkData.timeStamp = timeStamp;

      case 'INST',  % Instrument Chunk

        chunkData.baseNote = fread(fid,1,'int8');
        chunkData.detune = fread(fid,1,'int8');
        chunkData.lowNote = fread(fid,1,'int8');
        chunkData.highNote = fread(fid,1,'int8');
        chunkData.lowVelocity = fread(fid,1,'int8');
        chunkData.highVelocity = fread(fid,1,'int8');
        chunkData.gain = fread(fid,1,'int16');
        chunkData.sustainLoop = read_loop(fid);
        chunkData.releaseLoop = read_loop(fid);

      case 'MARK',  % Marker Chunk

        nMarkers = fread(fid,1,'uint16');
        chunkData.nMarkers = nMarkers;
        chunkData.markerArray = struct('id',cell(nMarkers,1),...
                                       'position',[],'markerName',[]);
        for iMarker = 1:nMarkers,
          chunkData.markerArray(iMarker) = read_marker(fid);
        end
        markerIDs = [chunkData.markerArray.id];
        if any(markerIDs < 1) || (numel(unique(markerIDs)) < nMarkers),
          warning('aiffread:invalidMarkers',...
                  'Invalid or repeated marker IDs were detected.');
        end

      case 'MIDI',  % MIDI Data Chunk

        chunkData.midiData = fread(fid,[chunkSizeArray{iChunk} 1],...
                                   '*uint8');

      case 'NAME',  % Name Chunk

        chunkData.text = read_text(fid,chunkSizeArray{iChunk});

      case 'SAXL',  % Sound Accelerator (SAXEL) Chunk (AIFC/AIFF-C only)

        nSaxels = fread(fid,1,'uint16');
        chunkData.nSaxels = nSaxels;
        chunkData.saxelArray = struct('id',cell(nSaxels,1),'size',[],...
                                      'saxelData',[]);
        for iSaxel = 1:nSaxels,
          chunkData.saxelArray(iSaxel) = read_saxel(fid);
        end

      case 'SSND',  % Sound Data Chunk

        nBytes = ceil(nBits/8);
        chunkData.offset = fread(fid,1,'uint32');
        chunkData.blockSize = fread(fid,1,'uint32');
        if isempty(indexRange),
          data = [nSampleFrames nChannels];
        elseif strcmp(compressionType,'NONE'),
          if (chunkSizeArray{iChunk}-8 ~= nChannels*nSampleFrames*nBytes),
            error(error_message('sizeMismatch'));
          end
          fseek(fid,nBytes*nChannels*(indexRange(1)-1),'cof');
          nRead = min(indexRange(2),nSampleFrames)-indexRange(1)+1;
          data = fread(fid,[nChannels nRead],['*bit' int2str(nBytes*8)]).';
          if nBits < nBytes*8,
            data = data./(2^(nBytes*8-nBits));
          end
        else
          data = fread(fid,[chunkSizeArray{iChunk}-8 1],'*int8');
        end

    end
    formChunk.chunkArray(iChunk).chunkData = chunkData;
  end

  % Close the file:

  fclose(fid);

%~~~Begin nested functions~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  %------------------------------------------------------------------------
  function errorStruct = error_message(errorCode,varargin)
  %
  %   Initialize an error message (and close open files, if necessary).
  %
  %------------------------------------------------------------------------

    % Close open files, if necessary:

    if ~isempty(fopen(fid)),
      fclose(fid);
    end

    % Initialize error message text:

    switch errorCode,
      case 'badArgumentType',
        errorText = [varargin{1} ' should be of type ' varargin{2} '.'];
      case 'badIndexValue',
        errorText = ['Index range must be specified as a scalar or ' ...
                     '2-element vector of positive, non-zero, non-NaN ' ...
                     'values.'];
      case 'invalidFile',
        errorText = ['Could not open file ''' varargin{1} '''.'];
      case 'invalidFileFormat',
        errorText = ['Not a valid ' varargin{1} ' file.'];
      case 'invalidString',
        errorText = '''size'' is the only valid string argument.';
      case 'missingChunk',
        errorText = ['''' varargin{1} ''' chunk is required for a ' ...
                     varargin{2} ' file.'];
      case 'notEnoughInputs',
        errorText = 'Not enough input arguments.';
      case 'repeatChunk',
        errorText = ['The following chunk IDs should not appear more ' ...
                     'than once in an ' varargin{1} ' file: ' varargin{2}];
      case 'sizeMismatch',
        errorText =  'Data size mismatch between COMM and SSND chunks.';
      case 'unknownExtension',
        errorText = ['Unknown file extension ''' varargin{1} '''.'];
    end

    % Create error structure:

    errorStruct = struct('message',errorText,...
                         'identifier',['aiffread:' errorCode]);

  end

%~~~End nested functions~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

end

%~~~Begin subfunctions~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

%--------------------------------------------------------------------------
function value = extended2double(exponent,highMantissa,lowMantissa)
%
%   Converts an 80-bit extended floating-point type to a double.
%
%--------------------------------------------------------------------------

  signBit = bitand(exponent,32768);
  exponent = bitand(exponent,32767);
  highMantissa = bitand(highMantissa,4294967295);
  lowMantissa = bitand(lowMantissa,4294967295);
  if (exponent == 0) && (highMantissa == 0) && (lowMantissa == 0),
    value = 0;
  elseif exponent == 32767,
    if (highMantissa > 0) || (lowMantissa > 0),
      value = nan;
    else
      value = inf;
    end
  else
    value = highMantissa*2^(exponent-16414)+lowMantissa*2^(exponent-16446);
  end
  if signBit,
    value = -value;
  end

end

%--------------------------------------------------------------------------
function commentStruct = read_comment(fid)
%
%   Reads a structure of comment data from a file.
%
%--------------------------------------------------------------------------

  commentStruct = struct('timeStamp',fread(fid,1,'uint32'),...
                         'marker',fread(fid,1,'int16'),...
                         'count',[],'text',[]);
  charCount = fread(fid,1,'uint16');
  commentStruct.count = charCount;
  commentStruct.text = read_text(fid,charCount);

end

%--------------------------------------------------------------------------
function loopStruct = read_loop(fid)
%
%   Reads a structure of loop data from a file.
%
%--------------------------------------------------------------------------

  loopStruct = struct('playMode',fread(fid,1,'int16'),...
                      'beginLoop',fread(fid,1,'int16'),...
                      'endLoop',fread(fid,1,'int16'));

end

%--------------------------------------------------------------------------
function markerStruct = read_marker(fid)
%
%   Reads a structure of marker data from a file.
%
%--------------------------------------------------------------------------

  markerStruct = struct('id',fread(fid,1,'int16'),...
                        'position',fread(fid,1,'uint32'),...
                        'markerName',read_pstring(fid));

end

%--------------------------------------------------------------------------
function pascalString = read_pstring(fid)
%
%   Reads a Pascal-style string from a file, and afterwards shifts the file
% pointer ahead by one byte if necessary to make the total number of bytes
% read an even number.
%
%--------------------------------------------------------------------------

  charCount = fread(fid,1,'uint8');
  pascalString = fread(fid,[1 charCount],'int8=>char');
  if rem(charCount+1,2),
    fseek(fid,1,'cof');
  end

end

%--------------------------------------------------------------------------
function saxelStruct = read_saxel(fid)
%
%   Reads a structure of saxel data from a file.
%
%--------------------------------------------------------------------------

  saxelStruct = struct('id',fread(fid,1,'int16'),'size',[],'saxelData',[]);
  saxelBytes = fread(fid,1,'uint16');
  saxelStruct.size = saxelBytes;
  saxelStruct.saxelData = fread(fid,[saxelBytes 1],'*int8');
  if rem(saxelBytes,2),
    fseek(fid,1,'cof');
  end

end

%--------------------------------------------------------------------------
function textString = read_text(fid,charCount)
%
%   Reads ASCII text from a file, and afterwards shifts the file pointer
% ahead by one byte if necessary to make the total number of bytes read an
% even number.
%
%--------------------------------------------------------------------------

  textString = fread(fid,[1 charCount],'int8=>char');
  if rem(charCount,2),
    fseek(fid,1,'cof');
  end

end

%~~~End subfunctions~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~