comparison core/magnatagatune/MTTAudioFeatureSlaney08.m @ 0:e9a9cd732c1e tip

first hg version after svn

+classdef MTTAudioFeatureSlaney08 < MTTAudioFeature & handle
+    % ---
+    % This Class contains 
+    % a basic summary of MTT features complementary to those in
+    % MTTAudioFeatureBasicSm,  features are extracted 
+    % as described in Slaney 08 - LEARNING A METRIC FOR MUSIC SIMILARITY
+    %
+    % The usual workflow for these features constist of three steps
+    % 1. extract: extracts the basic single-file dependent features
+    % 2. define_global_transform: calculates the global feature
+    %       transformation parameters
+    % 3. finalise: applies the common transformations to a specific feature
+    % ---
+    
+    properties(Constant = true)
+        
+        % svn hook
+        my_revision = str2double(substr('$Rev$',  5, -1));
+    end
+
+    properties
+        % ---
+        % Set default parameters
+        % ---
+        my_params = struct(...
+            'norm_mttstats', 1, ... % 
+            'whiten_mttstats', 0, ... % NOTE: whitening as in slaney?? 
+            'select_mttstats', 1 ...% TODO: way to select certain features
+            );
+    end
+    
+    % ---
+    % member functions
+    % ---
+    methods
+        
+        % ---
+        % constructor: pointer to feature in database
+        % ---
+        function feature = MTTAudioFeatureSlaney08(varargin)
+
+            feature = feature@MTTAudioFeature(varargin{:});
+
+        end
+        % ---
+        % extract feature data from raw audio features
+        % ---
+        function data = extract(feature, clip)
+            % ---
+            % get features. this includes possible
+            % local normalisations
+            % ---
+            
+            global globalvars;
+            
+            % --- 
+            % get casimir child clip if available
+            % ---
+            if isa(clip, 'CASIMIRClip')
+                baseclip = clip.child_clip();
+            else
+                baseclip = clip;
+            end
+            if isa(baseclip, 'MTTClip') 
+                rawf = baseclip.audio_features_raw();
+            elseif isa(baseclip, 'MSDClip')
+                rawf = baseclip.features('MSDAudioFeatureRAW');
+            end
+            
+                        
+            % ---
+            % TODO: implement time_weighted version of the statistical 
+            % evaluations below
+            % ---
+            
+%             segmentDurationMean: mean segment duration (sec.).
+            data.mttstats.segmentDurationMean = mean(rawf.data.segments_duration);
+
+%             segmentDurationVariance: variance of the segment duration 
+            data.mttstats.segmentDurationVariance = var(rawf.data.segments_duration);
+
+%             timeLoudnessMaxMean: mean time to the segment maximum, or attack duration (sec.).
+            data.mttstats.timeLoudnessMaxMean = mean(rawf.data.segments_loudness_max_time);
+
+%             loudnessMaxMean: mean of segments’ maximum loudness(dB).
+            data.mttstats.loudnessMaxMean = mean(rawf.data.segments_loudness_max);
+            
+%             loudnessMaxVariance: variance of the segments’ maximum loudness (dB).
+            data.mttstats.loudnessMaxVariance = var(rawf.data.segments_loudness_max);
+            
+%             loudnessBeginMean: average loudness at the start of segments (dB)
+            data.mttstats.loudnessBeginMean = mean(rawf.data.segments_loudness);
+
+%             loudnessBeginVariance: variance of the loudness at the startof segments (dB2). Correlated with loudnessMaxVariance
+            data.mttstats.loudnessBeginVariance = var(rawf.data.segments_loudness);
+
+%             loudnessDynamicsMean: average of overall dynamic rangein the segments (dB).
+%             loudnessDynamicsVariance: segment dynamic range variance
+%             (dB). Higher variances suggest more dynamics ineach segment.
+            % ---
+            % NOTE: the above information cannot be extracted from the MTT 
+            % Features, maybe more recent echonest features allow for this
+            % ---
+
+%             loudness: overall loudness estimate of the track (dB).  
+            data.mttstats.loudness = rawf.data.loudness;
+
+            % ---
+            % TODO: get these from the beat loundesses?
+            % ---
+            
+%             tempo: overall track tempo estimate (in beat per minute,BPM). Doubling and halving errors are possible.
+            data.mttstats.tempo = rawf.data.tempo;
+
+%             tempoConfidence: a measure of the con?dence of the tempo estimate (beween 0 and 1).
+            %data.mttstats.tempoConfidence = rawf.data.tempoConfidence;
+            
+            beats = rawf.data.beats;
+            tatums = rawf.data.tatums;
+            
+%             beatVariance: ameasure of the regularity of the beat (secs).
+            if numel(beats) > 0
+                bdiff = diff(beats(1,:));
+                data.mttstats.beatVariance = var(bdiff);
+            else
+                
+                % ---
+                % This is a facke repolacement variance
+                % ---
+                data.mttstats.beatVariance = 0;
+            end
+            
+            
+%             tatum: estimated overall tatum duration (in seconds). Tatums are subdivisions of the beat.
+            % ---
+            % note: the tatum length could be also 
+            % accessed by comparison with the global bpm estimate
+            % ---
+            if numel(tatums) > 0
+                tdiff = diff(tatums(1,:));
+                data.mttstats.tatum = median(tdiff);
+                
+    %             tatumConfidence: a measure of the con?dence of the tatum estimate (beween 0 and 1).
+                data.mttstats.tatumConfidence = mean(tatums(2,:));
+
+    %             numTatumsPerBeat: number of tatums per beat
+                data.mttstats.numTatumsPerBeat = median(bdiff) / data.mttstats.tatum;
+            else
+                % ---
+                % This is a facke replacement tatum
+                % TODO: maybe set confidence to -1?
+                % ---
+                
+                data.mttstats.tatum = 0;
+                
+    %             tatumConfidence: a measure of the con?dence of the tatum estimate (beween 0 and 1).
+                
+                data.mttstats.tatumConfidence = 0;
+
+    %             numTatumsPerBeat: number of tatums per beat
+                data.mttstats.numTatumsPerBeat = 2;  
+            end
+            
+            
+            % ---
+            % TODO: beat analysis
+            % ---
+
+%             timeSignature: estimated time signature (number of beats per measure).  (0-7 / 7)
+            data.mttstats.timeSignature = rawf.data.timeSignature;
+            
+%             timeSignatureStability: a rough estimate of the stability of the time signature throughout the track
+            data.mttstats.timeSignatureStability = rawf.data.timeSignatureConfidence;
+            
+            % ---
+            % prepare field for final features
+            % ---
+            data.final.vector = [];
+            data.final.vector_info = struct(); 
+            data.final.dim = 0;
+           
+            % save info data
+            data.info.type = 'MTTAudioFeatureSlaney08';
+            data.info.owner_id = clip.id;
+            data.info.creatorrev = feature.my_revision;
+            
+            % save parameters
+            data.info.params = feature.my_params;
+        end
+        
+        function define_global_transform(features)
+        % calculate and set normalization factors from the group of 
+        % input features. These features will be set for the full database
+                    
+         for i = 1:numel(features)
+                data = features(i).data.mttstats;
+
+                final(:,i) = [data.segmentDurationMean; ...
+                    data.segmentDurationVariance; ...
+                    data.timeLoudnessMaxMean; ...
+                    data.loudnessMaxMean; ...
+                    data.loudnessMaxVariance; ...
+                    data.loudnessBeginMean; ...
+                    data.loudnessBeginVariance; ...
+                    data.loudness; ...
+                    data.tempo; ...
+                    ... % data.tempoConfidence; ...
+                    data.beatVariance; ...
+                    data.tatum; ...
+                    data.tatumConfidence; ...
+                    data.numTatumsPerBeat; ...
+                    data.timeSignature; ...
+                    data.timeSignatureStability];
+         end
+            
+            if features(1).my_params.norm_mttstats
+                if numel(features) == 1
+                    error ('Insert feature array for this method, or set normalisation to 0');
+                end
+
+                % ---
+                % here, we only need to define the post-normalisation
+                % ---
+                [final, pstd] = mapminmax(final,0,1);
+                common.mttstats.pre_norm = pstd;
+                
+                % ---
+                % NOTE: whitening as in slaney?? 
+                % Would make reading the
+                % mahal matrices really hard
+                % ---
+                
+                features(1).my_db.set_common(common);
+                
+            else
+                
+                features(1).my_db.set_common([1]);
+            end
+            
+            % save the normalised features straight away!
+            features.finalise(final);
+        end
+        
+        
+        function finalise(features, final)
+        % applies a final transformation and
+        % collects the information of this feature within a single vector
+        % see info for types in specific dimensions
+        % check if features have been finalised already
+
+        % ---
+        % check for dummy feature
+        % ---
+        if isfield(features(1).my_params,'select_mttstats') && ...
+            isnumeric(features(1).my_params.select_mttstats) && ...
+            features(1).my_params.select_mttstats == 0
+            
+            % if no information needed just fill everything 0
+            for i = 1:numel(features)
+                features(i).data.final.vector = [];
+                features(i).data.final.dim = 0;
+
+                % fill up info struct and append to feature
+                features(i).data.final.vector_info.labels = {};
+            end
+            
+            return;
+        end
+        
+        % ---
+        % set feature labelling
+        % ---
+        info = {'segmentDurationMean', ...
+        'segmentDurationVariance', ...
+        'timeLoudnessMaxMean', ...
+        'loudnessMaxMean', ...
+        'loudnessMaxVariance', ...
+        'loudnessBeginMean', ...
+        'loudnessBeginVariance', ...
+        'loudness', ...
+        'tempo', ...
+        ...% 'tempoConfidence', ...
+        'beatVariance', ...
+        'tatum', ...
+        'tatumConfidence', ...
+        'numTatumsPerBeat', ...
+        'timeSignature', ...
+        'timeSignatureStability'};
+                
+        % ---
+        % construct resulting feature vector out of features
+        % ---
+            if nargin == 2 && isempty(final)
+                
+                % the final vector etc already are set to zero;
+                return;
+                
+            elseif nargin == 2 && (numel(features) == size(final, 2))
+                for i = 1:numel(features)
+
+                    % check for neccesary parameters
+                    if isempty(features(i).my_db.commondb)
+
+                        error('Define the global transformation first')
+                        return;
+                    end
+
+                    features(i).data.final.vector = final(:,i);
+                    features(i).data.final.dim = size(final,1);
+
+                    % fill up info struct and append to feature
+                    features(i).data.final.vector_info.labels = info;
+                end
+            else
+                % ---
+                % if features have been added after gettin gnormalisation
+                % parameters, ther should be still an option to include
+                % them
+                % ---
+                  
+                 for i = 1:numel(features)
+
+                    % check for neccesary parameters
+                    if isempty(features(i).my_db.commondb)
+
+                        error('Define the global transformation first')
+                        return;
+                    end
+                    
+                    data = features(i).data.mttstats;
+                    final = [data.segmentDurationMean; ...
+                        data.segmentDurationVariance; ...
+                        data.timeLoudnessMaxMean; ...
+                        data.loudnessMaxMean; ...
+                        data.loudnessMaxVariance; ...
+                        data.loudnessBeginMean; ...
+                        data.loudnessBeginVariance; ...
+                        data.loudness; ...
+                        data.tempo; ...
+                        ... % data.tempoConfidence; ...
+                        data.beatVariance; ...
+                        data.tatum; ...
+                        data.tatumConfidence; ...
+                        data.numTatumsPerBeat; ...
+                        data.timeSignature; ...
+                        data.timeSignatureStability];
+                    
+                    if features(1).my_params.norm_mttstats == 1
+                                
+                        [final] = mapminmax('apply', final, features(1).common.mttstats.pre_norm);
+                    end
+                    
+                    features(i).data.final.vector = final;
+                    features(i).data.final.dim = size(final,1);
+
+                    % fill up info struct and append to feature
+                    features(i).data.final.vector_info.labels = info;
+                 end
+
+            end
+            
+            % ---
+            % TODO: Maybe delete more basic features again at this point?
+            % ---
+        end
+
+        % ---
+        % destructor: do we really want to remove this 
+        % from the database? No, but 
+        % TODO: create marker for unused objects in db, and a cleanup
+        %  function
+        % ---
+        function delete(feature)
+            
+        end
+    end
+end