audiorec(Fs, th, opts)

function out = audiorec(Fs, th, opts)
% out = audiorec(Fs, th, opts)
%==========================================================================
% Monitor the sound card (or any other analog input device) for an event,
% i.e. when the input level on one of the channels exceeds some threshold. 
% Once the event has occurred, the function returns a struct with the 
% recorded signals.
%
% NOTE: The function requires the Data Acquisition Toolbox to be installed 
% on the system.
%
% Input: Fs   (optional) - Sampling frequency (Hz)
%        th   (optional) - Threshold (between 0 and 1).
%        opts (optional) - Struct (described below) specifying additional
%                          options.
%        dev  (optional) - Analog input device to use (optional). 
%                          Default is 'winsound'.
%
% Output: A stuct with the following fields
%         out.X  - The recorded audio X (each channel in one
%                  column.
%         out.t  - Time vector
%         out.Fs - Sampling frequency
%
% The optional struct should contain the following fields:
%
%  opts.duration  - Total duration of the sampled audio (in seconds).
%  opts.pretrig   - Amount (in seconds) of data to be kept before the
%                   triggering event occurred (>= zero).
%  opts.channels  - Input channels to use (e.g. [1,2]) 
%  opts.trig      - Channel to use as trigger source.
%  opts.dev       - Input device. Default is 'winsound'
% 
% EXAMPLE: see the accompanying file, test_audiorec.m
%
%==========================================================================
% Version 1.0
%--------------------------------------------------------------------------
% Created: November 14, 2008, by Johan E. Carlson
% Last modified: November 15, 2008, by Johan E. Carlson
%==========================================================================

%--------------------------------------------------------------------------
% Parse input and assign default values if necessary
%--------------------------------------------------------------------------
if nargin < 1,
    Fs = 44100;        % Default sampling frequency 44.1 kHz
end

%--------------------------------------------------------------------------
% If no trigger level (sound level threshold) is specified, set default.
%--------------------------------------------------------------------------
if nargin < 2,
    th = 0.5;          % Default sound level threshold.
end

%--------------------------------------------------------------------------
% If no options are spcified, set default, otherwise look into the opts
% struct.
%--------------------------------------------------------------------------
if nargin < 3,
    duration = 0.15;   % Default recording length (in seconds)
    pretrig = 0.5;     % Default pre-trigger length (in seconds)
    channels = 1;      % Default input channel
    trigger = 1;       % Default trigger source
    dev = 'winsound';  % Default input device
else
    duration = opts.duration;
    pretrig = opts.pretrig;
    channels = opts.channels;
    trigger = opts.trig;
    dev = opts.device;
end

%--------------------------------------------------------------------------
% Setup audio interface
%--------------------------------------------------------------------------
AI = analoginput(dev);                 % Default windows audio interface
ch = addchannel(AI,channels);          % Activate channels
set(AI,'SampleRate',Fs);               % Set sampling rate

set(AI,'TriggerFcn',@triggerfunction); % Function to call when event occurs
set(AI,'TriggerChannel',ch(trigger));  % Set trigger source
set(AI,'TriggerType','Software');      % Set software trigger mode
set(AI,'TriggerCondition','Rising');   % Trigger on rising waveform 
set(AI,'TriggerConditionValue',th);    % Set trigger level
set(AI,'TriggerDelay',-pretrig);       % Set pre-trigger amount
ActualRate = get(AI,'SampleRate');     % Check sample rate
if ActualRate ~= Fs,
    disp(['Warning: Sampling rate changed to ', num2str(ActualRate)]);
end
set(AI,'SamplesPerTrigger',duration*ActualRate);  % Set sample duration

%--------------------------------------------------------------------------
% Start the analog input device.
%--------------------------------------------------------------------------
start(AI);

%--------------------------------------------------------------------------
% Do absolutely nothing until the sound event occurred.
%--------------------------------------------------------------------------
while isrunning(AI),
end
pause(0.1);  % Short pause to allow for things to settle. 
             % This may have to be increased on other systems.

%--------------------------------------------------------------------------
% Prepare output struct.
%--------------------------------------------------------------------------
out.X = X;
out.t = t;
out.Fs = Fs;

%--------------------------------------------------------------------------
% Cleanup
%--------------------------------------------------------------------------
delete(AI);

%==========================================================================
% Below is the function that will be invoked when a sound event occurs.
%==========================================================================
function triggerfunction(obj,events)

[x,t] = getdata(obj);
assignin('caller','X',x);
assignin('caller','t',t);
stop(obj);