read_audio_stim

 Reads in the information for an mp3 audio stim file from the stimulus table.

 [sig,fs,nbits,opts] = read_audio_stim(stimulus_id,N,mono,downsamp,mysql_conn_id)

 Accepts a stimulus_id, and optional parameters: N (the max. number of frames
 to read), mono (set to 1 to convert output to mono, 0 if no conversion), and
 downsamp, the downsampling factor

 The parameter values can either be passed into the function in the fixed
 order shown above, or alternatively, as tag/value pairs

 Optionally, a mysql connection ID (mysql_conn_id) can be passed
 for communicating with the database. If this is omitted, the
 function will still be able to connect with the database, but
 this connection will result in connection information printing on
 the matlab console each time the function is called.

 The output variables are the same as those for wavread: sig (the signal 
 vector or matrix), fs (the sampling rate), nbits (number of bits per sample),
 and opts (a format info string).

0001 function [sig,fs,nbits,opts] = read_audio_stim(stimulus_id,varargin)
0002 % Reads in the information for an mp3 audio stim file from the stimulus table.
0003 %
0004 % [sig,fs,nbits,opts] = read_audio_stim(stimulus_id,N,mono,downsamp,mysql_conn_id)
0005 %
0006 % Accepts a stimulus_id, and optional parameters: N (the max. number of frames
0007 % to read), mono (set to 1 to convert output to mono, 0 if no conversion), and
0008 % downsamp, the downsampling factor
0009 %
0010 % The parameter values can either be passed into the function in the fixed
0011 % order shown above, or alternatively, as tag/value pairs
0012 %
0013 % Optionally, a mysql connection ID (mysql_conn_id) can be passed
0014 % for communicating with the database. If this is omitted, the
0015 % function will still be able to connect with the database, but
0016 % this connection will result in connection information printing on
0017 % the matlab console each time the function is called.
0018 %
0019 % The output variables are the same as those for wavread: sig (the signal
0020 % vector or matrix), fs (the sampling rate), nbits (number of bits per sample),
0021 % and opts (a format info string).
0022 
0023 % July 8, 2005 Original Version S.T.
0024 % Sept. 15, 2005 Modified by S.T. use mp3read matlab function instead of sox
0025 % Dec. 7, 2005 Mod. by S.T. read stims from nfs space rather than copy to localhost using scp
0026 % May 6, 2010 S.T. - added support for wav files. Since wavread doesn't support
0027 %                    downsampling, this function simply reports an error if downsampling was set
0028 %                    to a value other than one and a wav file was specified
0029 % 06/15/10 PJ - mysql_make_conn sanitization.  Input variable handling
0030 %               still needs cleanup
0031 % 03Jun2015 PJ - improved handling of input variables
0032   
0033 ensemble_globals;
0034 
0035 % Try to determine if we are calling the function using tag/value pairs or
0036 % specific values in specific positions
0037 using_dict_input = false;
0038 
0039 if nargin > 1 && all(cellfun(@ischar, varargin(1:2:end)))
0040   using_dict_input = true;
0041 end
0042 
0043 % Initialize parameters
0044 mysql_conn_id = [];
0045 mono = 0;
0046 downsamp = 1;
0047 N = [];
0048 
0049 if using_dict_input
0050   for iarg = 1:2:length(varargin)
0051     switch varargin{iarg}
0052       case 'conn_id'
0053         mysql_conn_id = varargin{iarg+1};
0054         
0055       case 'stimulus_root'
0056         stimulus_root = varargin{iarg+1};
0057         
0058       case 'mono'
0059         mono = varargin{iarg+1};
0060         
0061       case 'downsamp'
0062         downsamp = varargin{iarg+1};
0063         
0064       case 'N'
0065         N = varargin{iar+1};
0066     end
0067   end
0068 else
0069   switch(nargin)
0070     case 1
0071       N = [];
0072       mono = 0;
0073       downsamp = 1;
0074     case 2
0075       N = varargin{1};
0076       mono = 0;
0077       downsamp = 1;
0078     case 3
0079       N = varargin{1};
0080       mono = varargin{2};
0081       downsamp = 1;
0082     case {4,5,6}
0083       N = varargin{1};
0084       mono = varargin{2};
0085       if(isempty(varargin{3}))
0086         downsamp = 1;
0087       else
0088         downsamp = varargin{3};
0089       end
0090   end
0091 end
0092 
0093 if isempty(mysql_conn_id)
0094   if(nargin < 5)
0095     mysql_conn_id = 7;
0096   else
0097     mysql_conn_id = varargin{4};  % doesn't this defy the purpose of varargin?
0098   end
0099 end
0100 
0101 if ~using_dict_input && nargin > 5
0102   params = varargin{5};
0103 else
0104   params = [];
0105 end
0106 
0107 if(nargin == 0)
0108   error('Need a stimulus_id from the stimulus table. Type ''help read_audio_stim'' for more information.');
0109 end
0110 
0111 if ~exist('mysql_conn_id','var') || isempty(mysql_conn_id)
0112   error('Unspecified mysql conn_id')
0113 else
0114   mysqlFail = false;
0115 end
0116 
0117 % Check for valid connection to database
0118 maxTries = 30;
0119 numTries = 0;
0120 forceStatusCheck = true;
0121 while forceStatusCheck && ~mysqlFail && mysql(mysql_conn_id,'status') && numTries < maxTries
0122   numTries=numTries+1;
0123   pause(rand*2)
0124   fprintf('.')
0125 end
0126 
0127 if forceStatusCheck && (numTries == maxTries)
0128   mysqlFail = true;
0129 end
0130   
0131 % Get a temporary connection ID if necessary. This means we have to pass in
0132 % a params struct though
0133 usingTmpConnID = false;
0134 if mysqlFail && ~isempty(params) && isfield(params,'mysql')
0135   fprintf('Trying to establish alternate connection\n');
0136   for iport = setdiff(0:9,mysql_conn_id)
0137     if ~mysql(iport,'status')
0138       params.mysql.conn_id = iport;
0139       mysql_conn_id = mysql_make_conn(params.mysql);
0140       usingTmpConnID = true;
0141       mysqlFail = false;
0142       fprintf('Established alternate connection: %d\n', mysql_conn_id);
0143       break
0144     end
0145     pause(rand*5)
0146   end
0147   if ~usingTmpConnID
0148     error('Tried, but failed to get an open port: last tried: %d', iport)
0149   end
0150 end
0151   
0152 if mysqlFail
0153   error('%s: Do not have a valid connection ID to read stimulus_id: %d; Tried %d times on conn_id: %d', ...
0154     mfilename, stimulus_id, numTries, mysql_conn_id);
0155 elseif numTries
0156   fprintf('Tried to reach database %d times\n', numTries);
0157 end
0158 
0159 sql_choose_stim = sprintf('select location from stimulus where stimulus_id = %d',stimulus_id);
0160 stim_location = mysql(mysql_conn_id,sql_choose_stim);
0161 
0162 if usingTmpConnID
0163   mysql(mysql_conn_id,'close')
0164 end
0165 
0166 stim_location = char(stim_location);
0167 
0168 %determine the file extension and use the appropriate sound file reader for
0169 %that extension
0170 [p,fstub,ext] = fileparts(stim_location);
0171 
0172 switch(ext) 
0173  case '.mp3'
0174   sfreader = @mp3read;
0175  case '.wav'
0176   sfreader = @wavread;
0177  otherwise
0178   error('Did not recognize sound file name extension');
0179 end
0180 
0181 %read the mp3 file
0182 if((downsamp ~= 1) && (strcmp(ext,'.wav')))
0183   error('This function doesn''t support downsampling of wav files. Wav files must be downsampled in the calling function.');
0184 end
0185 
0186 if(isempty(N) && (downsamp == 1))
0187   [sig,fs,nbits,opts] = sfreader(fullfile(stimulus_root,stim_location));
0188 elseif(~isempty(N) && (downsamp == 1))
0189   [sig,fs,nbits,opts] = sfreader(fullfile(stimulus_root,stim_location),N);
0190 elseif(isempty(N) && (downsamp ~= 1))
0191   %only mp3read supports this call (downsamp ~=1)
0192   [sig,fs,nbits,opts] = sfreader(fullfile(stimulus_root,stim_location),N,0,downsamp);
0193 elseif(~isempty(N) && (downsamp ~= 1))
0194   %only mp3read supports this call (downsamp ~=1)
0195   [sig,fs,nbits,opts] = sfreader(fullfile(stimulus_root,stim_location),N,0,downsamp);
0196 end
0197 
0198 if(mono)
0199   sig = mean(sig,2);
0200 end
0201