dicklyon@534: % Copyright 2012, Google, Inc.
dicklyon@534: % Author Richard F. Lyon
dicklyon@534: %
dicklyon@534: % This Matlab file is part of an implementation of Lyon's cochlear model:
dicklyon@534: % "Cascade of Asymmetric Resonators with Fast-Acting Compression"
dicklyon@534: % to supplement Lyon's upcoming book "Human and Machine Hearing"
dicklyon@534: %
dicklyon@534: % Licensed under the Apache License, Version 2.0 (the "License");
dicklyon@534: % you may not use this file except in compliance with the License.
dicklyon@534: % You may obtain a copy of the License at
dicklyon@534: %
dicklyon@534: %     http://www.apache.org/licenses/LICENSE-2.0
dicklyon@534: %
dicklyon@534: % Unless required by applicable law or agreed to in writing, software
dicklyon@534: % distributed under the License is distributed on an "AS IS" BASIS,
dicklyon@534: % WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
dicklyon@534: % See the License for the specific language governing permissions and
dicklyon@534: % limitations under the License.
dicklyon@534: 
dicklyon@536: function [naps, CF, BM] = CARFAC_Run_Segment(CF, input_waves, open_loop)
dicklyon@536: % function [naps, CF, BM] = CARFAC_Run_Segment(CF, input_waves, open_loop)
dicklyon@534: % 
dicklyon@534: % This function runs the CARFAC; that is, filters a 1 or more channel
dicklyon@534: % sound input segment to make one or more neural activity patterns (naps);
dicklyon@534: % it can be called multiple times for successive segments of any length,
dicklyon@534: % as long as the returned CF with modified state is passed back in each
dicklyon@534: % time.
dicklyon@534: %
dicklyon@534: % input_waves is a column vector if there's just one audio channel;
dicklyon@534: % more generally, it has a row per time sample, a column per audio channel.
dicklyon@534: %
dicklyon@534: % naps has a row per time sample, a column per filterbank channel, and
dicklyon@534: % a layer per audio channel if more than 1.
dicklyon@536: % BM is basilar membrane motion (filter outputs before detection).
dicklyon@534: %
dicklyon@534: % the input_waves are assumed to be sampled at the same rate as the
dicklyon@534: % CARFAC is designed for; a resampling may be needed before calling this.
dicklyon@534: %
dicklyon@534: % The function works as an outer iteration on time, updating all the
dicklyon@534: % filters and AGC states concurrently, so that the different channels can
dicklyon@534: % interact easily.  The inner loops are over filterbank channels, and
dicklyon@534: % this level should be kept efficient.
dicklyon@534: %
dicklyon@534: % See other functions for designing and characterizing the CARFAC:
dicklyon@534: % CF = CARFAC_Design(fs, CF_CAR_params, CF_AGC_params, n_ears)
dicklyon@534: % transfns = CARFAC_Transfer_Functions(CF, to_chans, from_chans)
dicklyon@534: 
dicklyon@536: if nargin < 3
dicklyon@536:   open_loop = 0;
dicklyon@536: end
dicklyon@536: 
dicklyon@536: if nargout > 2
dicklyon@536:   do_BM = 1;
dicklyon@536: else
dicklyon@536:   do_BM = 0;
dicklyon@536: end
dicklyon@536: 
dicklyon@534: [n_samp, n_ears] = size(input_waves);
dicklyon@534: 
dicklyon@534: if n_ears ~= CF.n_ears
dicklyon@534:   error('bad number of input_waves channels passed to CARFAC_Run')
dicklyon@534: end
dicklyon@534: 
dicklyon@534: n_ch = CF.n_ch;
dicklyon@534: naps = zeros(n_samp, n_ch, n_ears);  % allocate space for result
dicklyon@536: if do_BM
dicklyon@536:   BM = zeros(n_samp, n_ch, n_ears);
dicklyon@536: end
dicklyon@534: 
dicklyon@534: detects = zeros(n_ch, n_ears);
dicklyon@534: for k = 1:n_samp
dicklyon@534:   % at each time step, possibly handle multiple channels
dicklyon@534:   for ear = 1:n_ears
dicklyon@534:     [car_out, CF.CAR_state(ear)] = CARFAC_CAR_Step( ...
dicklyon@534:       input_waves(k, ear), CF.CAR_coeffs, CF.CAR_state(ear));
dicklyon@534:     
dicklyon@534:     % update IHC state & output on every time step, too
dicklyon@534:     [ihc_out, CF.IHC_state(ear)] = CARFAC_IHC_Step( ...
dicklyon@534:       car_out, CF.IHC_coeffs, CF.IHC_state(ear));
dicklyon@534:     
dicklyon@534:     detects(:, ear) = ihc_out;  % for input to AGC, and out to SAI
dicklyon@534:     naps(k, :, ear) = ihc_out;  % output to neural activity pattern  
dicklyon@536:     if do_BM
dicklyon@536:       BM(k, :, ear) = car_out;
dicklyon@536:     end
dicklyon@534:   end
dicklyon@534:   % run the AGC update step, taking input from IHC_state, 
dicklyon@534:   % decimating internally, all ears at once due to mixing across them:
dicklyon@534:   [CF.AGC_state, updated] = CARFAC_AGC_Step( ...
dicklyon@534:     CF.AGC_coeffs, detects, CF.AGC_state);
dicklyon@534:   
dicklyon@534:   % connect the feedback from AGC_state to CAR_state when it updates
dicklyon@536:   if updated & ~open_loop
dicklyon@534:     CF = CARFAC_Close_AGC_Loop(CF);
dicklyon@534:   end
dicklyon@534: end
dicklyon@534: