mathieu@14: function [] = simScene(inputPath,outputPath,score,varargin)
mathieu@14: % [] = simScene(inputPath,outputPath,score,[opts ... ])
mathieu@14: %
mathieu@14: % Generate a simulated auditory scene by mixing randomly chosen samples.
mathieu@14: % The samples and their mixing properties are chosen partially randomly
mathieu@14: % following user-provided guidelines.
mathieu@14: %
mathieu@14: % Required input variables are:
mathieu@14: %
mathieu@14: % - inputPath: a dataset of isolated sound events and backgrounds
mathieu@14: %             respectively located in inputPat/event/ and
mathieu@14: %             inputPat/background
mathieu@14: %
mathieu@14: % - outputPath: the repository where simscene will write the simulated scene
mathieu@14: %              as well as the annotations
mathieu@14: %
mathieu@14: % - score: a structure describing the scene to simulate
mathieu@14: %
mathieu@14: %   score.sceneDuration: length of the simulated scene in second
mathieu@14: %
mathieu@14: %   score.backgrounds: Backgrounds are continuous sounds that keep going
mathieu@14: %         over the whole duration of the scene. Several background samples
mathieu@14: %         may be mixed together. If 'sceneDuration' is  more than the
mathieu@14: %         natural length  of one of the selected bg sounds, they will be
mathieu@14: %         looped as necessary -- that may not sound great, depending on the
mathieu@14: %         sound... The format of the 'background' field controlling their
mathieu@14: %         selection   and use is:
mathieu@14: %
mathieu@14: %         {{'<bg 1 label>','<bg 1 sampleId>', 1},
mathieu@14: %          {'<bg 2 label>','<bg 2 sampleId>', <bg 2 snr>}...}
mathieu@14: %
mathieu@14: %         The value of 'snr' is ignored for the first bg sound. For the
mathieu@14: %         following ones, it will be evaluated against the sum of the
mathieu@14: %         previous ones. The value of 'Label' is the label of the
mathieu@14: %         background track. Simscene will use the value 'sampleId' to load
mathieu@14: %         the background sample(s) located in inputpath/background.
mathieu@14: %         Simscene will only use background sample(s) having a name
mathieu@14: %         containing the value 'sampleId'.
mathieu@14: %
mathieu@14: %  score.events: The 'events' is an array of cell arrays containg data use
mathieu@14: %        to  simulated the scenes. Event contains the following data:
mathieu@14: %
mathieu@14: %        {{'<event 1 label>',
mathieu@14: %          '<event 1 sampleId>',
mathieu@14: %           <event 1 ebr>,
mathieu@14: %           <event 1 ebr_stddev>,
mathieu@14: %           <event 1 mean_time_between_instances>,
mathieu@14: %           <event 1 time_between_instances_stddev>,
mathieu@14: %           <event 1 start_time>, 
mathieu@14: %           <event 1 end_time>,
mathieu@14: %           <event 1 fade_in_time>, 
mathieu@14: %           <event 1 fade_out_time>},
mathieu@14: %         {'<event 2 ...> ...},
mathieu@14: %         {'<event 3 ...> ...}
mathieu@14: %        ...}
mathieu@14: %
mathieu@14: %        If <mean_time_between_instances> is 0, then it will be set to the
mathieu@14: %        sample  length (so if <time_between_instances_stddev> is also 0,
mathieu@14: %        the sample will be looped).
mathieu@14: %        If <mean_time_between_instances> is -1, then the sound will be
mathieu@14: %        played just once. The considered EBR value is the maximum EBR
mathieu@14: %        of the fg sample relative to the bg on windows of 1000 samples.
mathieu@14: %        The considered bg for this is the  mix of all specified bgs.
mathieu@14: %
mathieu@14: %  This version of simscene allows a lot of options to be controlled, as
mathieu@14: %  optional  'name', value pairs from the 4th argument. Here is a brief 
mathieu@14: %  description of the optional parameters:
gregoirelafay@17: % save pictures without displaying them
mathieu@14: %  - timeMode: control a time spacing between events. 
mathieu@14: %  		'generate' (default): values must be set for each track using the 
mathieu@14: %                             score control structure
mathieu@14: %  		'abstract': values are computed from an abstract representation of 
mathieu@14: %                   an existing acoustic scene given as parameter
mathieu@14: %  		'replicate': values are replicated from an existing acoustic scene 
mathieu@14: %                    given as parameter
mathieu@14: %  		
mathieu@14: %  - ebrMode: control the Event to Background power level Ratio (EBR) of events. 
mathieu@14: %  		Possible options are: 'generate' (default), 'abstract', 'replicate', see above.
mathieu@14: %
mathieu@14: % If ebrMode is set to 'replicate' or 'abstract', and score.events exist, 
mathieu@14: % simScene will use the values <ebr> and <ebr_stddev> as offsets for 
mathieu@14: % the class <label>. 
mathieu@14: % If timeMode is set to 'abstract' and score.events exist, simScene will use 
mathieu@14: % the values <mean_time_between_instances> and <time_between_instances_stddev>.
mathieu@14: % as offsets for the class <label>. 
mathieu@14: % If one of the mode is not set to 'generate' and score.events exist, SimScene 
mathieu@14: % will also use the values <start_time>, <end_time>, <fade_in_time>,  <fade_out_time> 
mathieu@14: % and '<sampleId>' of score.events, provided they are not equal to 0 or
mathieu@14: % empty.
mathieu@14: %  		
mathieu@14: %  - instanceAnnotFile: if timeMode and / or ebrMode are set to 'abstract' 
mathieu@14: %                       or 'replicate', this parameter is the path to the 
mathieu@14: %                       annotation of the reference scene. Annotation must 
mathieu@14: %                       be provided as a Comma Separated Value (CSV) file 
mathieu@14: %                       with one event per line with class identifier as a 
mathieu@14: %                       string, onset and offset times in second as floating 
mathieu@14: %                       point value.
mathieu@14: %
mathieu@14: %  - instanceAudioFile: if timeMode and / or ebrMode are set to 'abstract' 
mathieu@14: %                       or 'replicate', this parameter is the path to the wav 
mathieu@14: %                       file of the reference scene sampled at 44100 Hz.
mathieu@14: %  
gregoirelafay@17: %  - figure: (default 0) save and show pictures (piano roll, time domain stacked visualization, overlaid spectrogram)
gregoire@16: %             0: don't save or display pictures
gregoire@16: %             1: save pictures without displaying them
gregoire@16: %             2: save and display pictures
gregoire@16: %
gregoirelafay@17: %  - channel: (default 0) number of audio channels contained in the file
gregoirelafay@17: %             0: 1 channel (mono)
gregoirelafay@17: %             1: As many channel as sound classes (events+textures)
gregoirelafay@17: %             2: As many channel as sound classes (events+textures). Each
gregoirelafay@17: %                channel is saved in a separated wav file.
gregoirelafay@17: %
mathieu@14: %  - outputFileName: name of generated files with no extension
mathieu@14: %  
mathieu@14: %  - sampleChoice: method for choosing sample to schedule within a track
mathieu@14: %  		'random': unconstrained sampling
gregoire@16: %       'random-unique': unconstrained sampling with no sample repetition
mathieu@14: %  		'close': choose among the sampling dataset the sample that 
mathieu@14: %                has the closest duration to the reference one. 
mathieu@14: %                This mode is available only for the replicate timeMode.
mathieu@14: %  
mathieu@14: %  - minSpace: floating point value (default -1: overlapping between events allowed): 
mathieu@14: %              minimal spacing in seconds between successive events
mathieu@14: %  
mathieu@14: %  - endCut: Boolean (default 0): adjust the duration of the last sample of 
mathieu@14: %            each track if the latter ends after the track duration. 
mathieu@14: %            If 1, cut the last sample to the track duration. If
mathieu@14: %            0, the last sample is removed.
mathieu@14: %
mathieu@14: %  SceneSchedule and SceneObject:
mathieu@14: %
mathieu@14: %  - sceneObjects: This vector will contain detailed information concerning 
mathieu@14: %                  all the samples selected to build this scene.
mathieu@14: %                    
mathieu@14: %  - sceneSchedule: This vector will contain all scheduling information 
mathieu@14: %                   (i.e. what sample goes where, with what scaling factor). 
mathieu@14: %                   The sample indices stored in it refer to the position 
mathieu@14: %                   in the previous vector.
mathieu@14: %
mathieu@14: %  SceneSchedule, SceneObject, as well as score are saved in the .mat
mathieu@14: %  annotation file.
mathieu@14: 
mathieu@14: % This program was written by Mathias Rossignol & Grégoire Lafay
mathieu@14: % is Copyright (C) 2015 IRCAM <http://www.ircam.fr>
mathieu@14: %
mathieu@14: % This program is free software: you can redistribute it and/or modify it
mathieu@14: % under the terms of the GNU General Public License as published by the Free
mathieu@14: % Software Foundation, either version 3 of the License, or (at your option)
mathieu@14: % any later version.
mathieu@14: %
mathieu@14: % This program is distributed in the hope that it will be useful, but
mathieu@14: % WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
mathieu@14: % or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
mathieu@14: % for more details.
mathieu@14: %
mathieu@14: % You should have received a copy of the GNU General Public License along
mathieu@14: % with this program.  If not, see <http://www.gnu.org/licenses/>.
mathieu@14: %
mathieu@14: % Uses Mark Paskin's process_options.m from KPMtools
mathieu@14: 
mathieu@14: addpath(genpath('nonExposed'));
mathieu@14: 
gregoire@24: [timeMode,ebrMode,instanceAnnotFile,instanceAudioFile,figuresOption,sampleChoice,outputFileName,minSpace,endCut,eventInfoPath,norm,channelsOption,noiseLevel,noiseFiltMaxFreq,noiseFiltOrder]=process_options(varargin,'timeMode','generate','ebrMode','generate','instanceAnnotFile','none','instanceAudioFile','none','figure',0,'sampleChoice','random','outputFileName','simulatedScene','minSpace',-1,'endCut',0,'eventInfoPath','','norm',.75,'channel',0,'noiseLevel',-24,'noiseFiltMaxFreq',0,'noiseFiltOrder',12);
gregoire@16: 
gregoire@16: sr=44100;
mathieu@14: 
mathieu@14: check_options(timeMode,ebrMode,score)
mathieu@14: 
mathieu@14: %% Get score (only if at least one of the modes is not set to generate).
mathieu@14: %  Else use score inpu variable
mathieu@14: if (~strcmp(timeMode,'generate') || ~strcmp(ebrMode,'generate'))
mathieu@14:     template=getTemplate(instanceAnnotFile,instanceAudioFile);
mathieu@14:     if isfield(score,'events')
mathieu@14:         score.events=addUserOffsets(template.class,score.events,timeMode,ebrMode);
mathieu@14:     else
mathieu@32:         fprintf(2, 'score.event is empty: score.event will be created from the scene to replicate');
mathieu@14:         score.events=template.class;
mathieu@14:     end
mathieu@14:     if ~isfield(score,'sceneDuration')
mathieu@14:         score.sceneDuration=template.sceneDuration;
mathieu@14:     end
mathieu@14: end
mathieu@14: 
mathieu@14: %% Get sceneSchedule and sceneObjects
gregoire@16: 
gregoire@16: if ~strcmp(eventInfoPath,'')
gregoire@16:     load(eventInfoPath);
gregoire@16: else
gregoire@18:     eventInfo(1).query='null';
gregoire@16: end
gregoire@16: 
gregoire@24: [sceneSchedule,sceneObjects,score]=getBackground(inputPath,score,eventInfo,sr,noiseLevel,noiseFiltMaxFreq,noiseFiltOrder);
gregoire@16: [sceneSchedule,sceneObjects]=getEvent(sceneSchedule,sceneObjects,inputPath,score,timeMode,ebrMode,sampleChoice,eventInfo,sr);
mathieu@14: 
mathieu@14: %% Manage overlapping
mathieu@14: if minSpace>=0
mathieu@14:     [sceneSchedule] = manageOverlapping(sceneSchedule,minSpace);
mathieu@14: end
mathieu@14: 
mathieu@14: 
mathieu@14: %% Generate Scene
mathieu@14: if (~exist(outputPath, 'dir'))
mathieu@14:     mkdir(outputPath)
mathieu@14: end
mathieu@14: if (~exist([outputPath,'annotation'], 'dir'))
mathieu@14:     mkdir([outputPath,'sound'])
mathieu@14: end
mathieu@14: if (~exist([outputPath,'annotation'], 'dir'))
mathieu@14:     mkdir([outputPath,'annotation'])
mathieu@14: end
mathieu@14: 
gregoirelafay@17: [sceneSchedule] = generateScene(sceneSchedule,sceneObjects,score,inputPath,outputPath,outputFileName,figuresOption,timeMode,endCut,norm,sr,channelsOption);
mathieu@14: 
mathieu@14: %% Check simulated scene
mathieu@14: 
mathieu@14: checkClassPresence(sceneSchedule,sceneObjects);
mathieu@14: 
mathieu@14: if minSpace>=0
mathieu@14:     checkOverlapping(sceneSchedule,score.sceneDuration)
mathieu@14: end
mathieu@14: 
mathieu@14: end