Changeset 2593 for Trunk/Scripts/Audio_scripts/AudioSegmentation/AudioBook.pm

Timestamp:

05/26/08 14:11:03 (6 months ago)

Author:

kmaclean

Message:

AudioSegmentation scripts -add POD docs

Files:

• Trunk/Scripts/Audio_scripts/AudioSegmentation/AudioBook.pm (modified) (12 diffs)

Trunk/Scripts/Audio_scripts/AudioSegmentation/AudioBook.pm

@@ -1 +1 @@
-#! /usr/bin/perl
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
-package AudioBook;
-use strict;
@@ -35 +19 @@
-use AudioBook::Text;
-use AudioBook::Dictionary;
+
+=head1 SYNOPSIS
+
+ $./AudioBook -h                                                                        display help
+ $./AudioBook -a speechfile.wav -t text.txt             minimal run configuration
+
+=head1 DESCRIPTION
+
+This program segments a speech audio file into 15 word (on average) speech segments.  It is executable from the command line and uses 
+the following configuration options to help in segmenting speech:
+
+        -a      * audio file name (WAV format only)
+        -b      beam width for Forced Alignment with HVit (default = 250)
+        -d      pronunciation dictionary  (default = AudioBook/input_files/VoxforgeDict)
+        -h      show help
+        -l      LICENSE file (default = AudioBook/input_files/LICENCE)
+        -m      Maximum sentence length (default = 20 words)
+        -p      Minimum pause for sentence break (default = 2000000 in units of 100ns)
+        -q      log words with single quotes (default = yes)
+        -r      README file (default = AudioBook/input_files/README)
+        -s      Average sentence length (default = 15 words)
+        -t      * text file name (containing transcriptions of speech in audio file)
+        -u      username or name you want file stats collected by on VoxForge Metrics 
+                page:   (http://www.voxforge.org/home/downloads/metrics)
+        -v      verify segments created from first pass Forced Alignment
+        -x      unique tar file suffix (max 3 characters - remainder is truncated)
+        -S      run sanity test
+        -T      create gzipped/tar file
+
+                * required for script to run
+
+=head2 NOTES
+
+=head3 Text Does not Match Audio
+
+If the contents of the text file do not *exactly* match the contents of the speech audio file, the segmentation process necessarily becomes 
+a manual, iterative process.
+
+If there are a large divergence in the text from the speech audio, then you will have to manually listen to the speech audio to determine 
+where the biggest transcription errors lie, and then modify the original text file to match the speech audio file.  
+
+If the transcription errors are minor, then the first pass forced alignment usually completes successfully.  However, if you see "No tokens survived to final node of network at beam" errors in the 
+HVite log (located in interim_files/logs), then using the "-v" verify switch might be helpful in determining where transcription problems 
+might exist.
+
+The verify switch performs a forced alignment on the individual segments generated from the first pass forced alignment.  Low scores 
+(i.e. the lowest average log likelihood per frame score) indicate that the transcription text might not match the corresponding audio 
+file.  Look at the segment text and listen to the corresponding audo file to determine if they match.  If they do not match, then fix the 
+text in your original text transcription file, repeat this process (i.e. running the AudioBook program again with the verify switch on) 
+until you can get a clean run.
+
+=head3 Segmenting large audio files
+
+For larger files (i.e. greater than 30 minutes of audio), you *may* need to manually segment the audio file into 30 minute segments.
+
+=head3 Automatically Adding Out-of-vocabulary words to pronunciation dictionary 
+
+The pronunciations generated by the Sequitor G2P scripts need to be manually reviewed before any new pronunciations are added to the
+pronunciation dictionary.  Make sure you review the pronunciation before commiting these changes to SVN.    
+
+=head1 REQUIREMENTS
+
+=item 1 - Sequitor G2P trainable Grapheme-to-Phoneme converter (which requires Python to be installed)
+                http://www-i6.informatik.rwth-aachen.de/web/Software/g2p.html
+
+=item 2 - HTK Hidden Markov Model Toolkit - note: the source is "open", but there are distribution restrictions
+                http://htk.eng.cam.ac.uk/
+
+=head1 ALGORITHM
+
+This program tries to segments the speech audio file into 15 word sentences.  However, if the pause following the 15th word relative to the current 
+sentence start position is too short, the algorithm looks at the previous word (i.e. word 14) to see if it has a pause of suitable duration.  
+If not, it then looks at word following the current start position (i.e. word 16), and so one until a pause of suitable
+duration can be found, increasing the number of words to look behind and ahead each time. 
+
+The default pause duration is 2000000 in units of 100ns.  This can be changed (using the "-p" switch") if the speech audio file does segment well 
+enough with this default.
+
+=head1 METHODS (not user accessible)
+
+=cut
+
-####################################################################
-### Class Variables
@@ -58 +124 @@
-
-####################################################################
-
-
+
+
+
+
+
+
+
+
+
-sub process {
-        my ($self)= @_;
@@ -91 +164 @@
-                close LOG
-        } 
-
+
+
+
+
-        my $audio = AudioBook::Audio->new($self);
-        $audio->segment($audiofile,$textContents);
@@ -102 +178 @@
-}
-
+=head2 cleanupFiles
+
+Removes any old files in the AudioBook/interim_files/ and AudioBook/output_files/ directories.
+
+=cut
+
-sub cleanupFiles {
-        my ($self)= @_;
@@ -121 +203 @@
-}
-
-
+
+
+
+
+
+
+
+
+
+
+
-        my ($self)= @_;
-        my $debug = $self->{'debug'};
@@ -166 +258 @@
-        return $randomString;
-}
+
+=head2 getOptions 
+
+Get the user submitted options ('a:b:d:hl:m:p:r:s:t:u:x:q:v:ST')
+
+=cut
-
-sub getOptions {
@@ -290 +388 @@
-                print "-r\tREADME file (default = AudioBook/input_files/README)\n";                             
-                print "-s\tAverage sentence length (default = $default_average_sentence_length words)\n";                               
-
+
+
-                print "-u\tusername or name you want file stats collected by on VoxForge Metrics \n";
-                print "\tpage:\t(http://www.voxforge.org/home/downloads/metrics)\n";    
+                
+                print "-v\tverify segments created from first pass Forced Alignment\n";
-                print "-x\tunique tar file suffix (max 3 characters - remainder is truncated)\n";
-                print "-S\trun sanity test\n";          
@@ -302 +403 @@
-                print "\nVoxForge Audio Segmentation Script\n"; 
-                print   "==================================\n"; 
-parms -a, -t, -d need to be defined, u
+Parms -a and -t need to be defined. U
-                exit;
-        }
@@ -310 +411 @@
-}
-
-
-
-
+
+
+
+
+
+
-sub getAverage_sentence_length {
-        my $self = shift;
@@ -318 +422 @@
-}
-
+=item * getMax_sentence_length()
+
+=cut
+
-sub getMax_sentence_length {
-        my $self = shift;
@@ -323 +431 @@
-}
-
+=item * getMin_pause_for_sentence_break()
+
+=cut
+
-sub getMin_pause_for_sentence_break {
-        my $self = shift;
-        return $self->{"max_sentence_length"};
-}
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+