foflc 2.35 Notes:

PURPOSE:
--------
Formerly named the "FoF Lyric Converter", this utility is intended to convert between various lyric formats and aid in creation of lyrics usable in the PC game FretsOnFire.  Currently supported formats for input are FretsonFire format script (script.txt), VividLyrics Editor (.vl), Rock Band/Guitar Hero/FretsonFire format MIDI files (.mid), UltraStar song format (.txt), Simple or Extended LRC lyric format (.lrc), Vocal Rhythm (.mid), Soft Karaoke (.kar), KAR (.kar), Synchronized ID3 lyrics (.mp3) and SRT subtitles (.srt).  Currently supported formats for output are FretsonFire format script, VividLyrics Editor, Rock Band/Guitar Hero/FretsonFire MIDI, UltraStar song format, Simple or Extended LRC format, Vocal Rhythm, Soft Karaoke, KAR, Synchronized ID3 lyrics and SRT subtitles.  Complete syntax and parameter information is as follows:


USAGE:
------
foflc	[-offset #] [-nohyphens [1|2|3]] [-noplus] [-marklines] [-nolyrics]
	[-grouping {word | line}] [-verbose | debug] [-filter [...]] [-quick] [-startstamp #]
	[-bpm #] [-brute] [-help] [-srcoffset #] [-intrack TRACKNAME] [-outtrack TRACKNAME]
	[-notenames] [-relative] [-nopitch] [-nosrctag [...]] [-nofstyle]
	{ {-detect infile} | {-id3tag infile} |
	  {{-in [FORMAT] infile (lyrics | vrhythmID)} {-out FORMAT (srcfile) outfile (lyrics)(vrhythmID)}} }

-The use of the "detect" or "id3tag" parameters will cause the program to run the requested function and end, ignoring any conversion specified by the other parameters.
-There must be white space (simply a space) between each parameter.  Parameters inside curly braces {} are required.  Parameters inside brackets [] are optional.  Parameters inside parantheses () are conditional based on the input or output format.  The lyrics parameter, for example, should only be provided when importing/exporting vocal rhythm format.  When typing parameters, do not type the curly braces {}, parantheses () or brackets [] themselves.
-Use "foflc -help" for a command-line summary of parameter syntax and descriptions.
-infile is the name of the input file.  If the FORMAT of the input file is specified, the file must be in the specified FORMAT that precedes it.  If the input FORMAT is omitted, it can be automatically detected.  If there is only one detected set of lyrics in the input file, that format will automatically be selected for import, otherwise the program will report that you need to specify the desired import format.  Automatic format detection isn't allowed for vocal rhythm, the format and both input files must be specified.  To correctly provide the input format and file to foflc, you must specify "-in" without quotation marks to designate that the following parameter(s) pertain to the input file, followed by the optional format that the file is in:  "script", "vl", "midi", "ustar", "lrc", "vrhythm", "kar", "skar", "id3" or "srt" (without quotation marks), followed by the input file name.  If the input file is a MIDI file, a text/lyric event in an imported MIDI track will be interpreted as a lyric event as long as the event's text does not begin with an open bracket '['.  The input file is not allowed to begin with a hyphen.
-If the input format is vrhythm, a source rhythm MIDI file (infile) containing the vocal timings must be specified, followed by either the input pitched lyrics file or the vrhythm track identifier.  Both files are unique in format to this import method.  An example of usage syntax for importing vocal rhythm is as follows:
	foflc -in vrhythm chart.mid pitchedlyrics.txt -out midi chartwithvocals.mid
If the vrhythm track ID is given instead of the pitched lyrics file, asterisks (*) are used in place of lyrics, similarly to how KAR/RB MIDIs are loaded when the -nolyrics parameter is used.  This allows you to create the vocal rhythm track, import it and export it back to vrhythm in order to create a pitched lyric file with the correct number of entries.  For example:
	foflc -in vrhythm myrhythm.mid G4 -out vrhythm temp.mid mylyrics.txt G4
Then, the exported vrhythm file (which will basically be a copy of the input file) can simply be deleted, and you're ready to edit the exported lyrics file to add the pitches and lyrics.  This will make it easy to ensure that the pitched lyric file and the vrhythm MIDI have the same number of vocal entries and avoid having to "debug" your vrhythm files.  Additionally, if you use one fret number (ie. fret 2) at the first lyric in each line, and all other lyrics in the line with a different fret number (ie. fret 1), lyricless vrhythm import will be able to insert line breaks accordingly, making it even easier to keep track of your place when adding the lyrics afterward.
-If the input format is kar, and no trackname is specified via command line, then the input file will be imported as a standard "Soft Karoke" KAR file, where lyrics are imported from the "Words" track with limited duration information and no pitch.  If an input trackname besides "Words" is specified, then the lyrics are imported with pitch and duration information (using the MIDI import logic) if it is available in the input file.

-outfile is the name of the output file, which will be created in the specified FORMAT that precedes it.  To correctly specify the output file to foflc, you must specify "-out" (without quotation marks, to designate that the following parameters pertain to the output file), followed by the format to export:  "script", "vl", "midi", "ustar", "lrc", "elrc", "vrhythm", "kar" (for unofficial KAR format), "skar" (for Soft Karaoke KAR format), "id3" or "srt" (without quotation marks), followed by the output file name.  The output file name may not begin with a hyphen.
-srcfile is an optional depending on the export format, and specifies the file from which content may be used toward the exported file.  For export formats that are MIDI based, such as MIDI or Vrhythm, if a source MIDI file is provided, the source MIDI's contents are copied as-is to the export file (except for the vocal track being written by the export) and the lyrics are written in the correct timing to merge with the source MIDI file.  This is the ideal way to merge the imported lyrics to a Frets on Fire chart that contains other playable instruments, as the instrument tracks are not altered at all in the process of adding vocals.  If a source MIDI file is not provided, then the exported file is created from scratch and uses a default timing of 120BPM.  An example of usage syntax for merging an UltraStar song text into a standalone MIDI that will contain only vocals and no instrument tracks:
	foflc -in ustar song.txt -out midi vocals.mid
An example of usage syntax for merging timed VL lyrics into an existing Frets on Fire chart is as follows:
        foflc -in vl myfile.vl -out midi notes.mid noteswithlyrics.mid
If the export format is ID3, then a source MP3 or other MPEG audio file must be specified, as an ID3 tag is only usable when embedded within an audio file.  If the import format is also ID3, the srcfile parameter may be omitted, in which case the program will use the input MP3 as the source MP3.  For ID3 export, any existing ID3 content (except for a Synchronized Lyrics frame) is copied to the ID3 tag that is written to the exported file, and all other content in the file (including audio content) is copied as-is to the exported file, so it's important to use the correct MP3 file as the source in order for the correct tag information to be copied to the output file.
-If the output format is vrhythm, the first parameter after "vrhythm" is the name of the vocal rhythm MIDI file to create.  The next parameter is the name of the pitched lyrics file to create.  The next parameter is the identifier of the instrument and difficulty to write the vocal rhythm notes into in the MIDI file.  These are the same identifiers as used during vocal rhythm import, which are described in the FORMAT SUMMARY section.  For example, to convert a VividLyrics file to vocal rhythm format, storing the rhythm notes in the Expert Guitar section:
	foflc -in vl myfile.vl -out vrhythm rhythm.mid pitchedlyrics.txt G4
The example above will write the lyrics as freestyle, as the VividLyrics format does not store pitch information.  The pitches can easily be entered by using any text editor to replace the # next to each lyric with the appropriate note name or pitch number.  To aid in the testing process, the first vocal rhythm note in each vocal phrase will be written on fret 2, and the others will be written on fret 1.
-If the output format is KAR and no output track name was specified (with -outtrack), the track name "Melody" will be used by default.


FORMAT SUMMARY:
---------------
Script-
	The original lyric format supported in modded versions of Frets on Fire, this file needs to be called "script.txt".  This pitchless format consists of optional tag information followed by a series of lyric definitions to be displayed line by line, like subtitles.  Each line definition has a starting timestamp, duration, the word "text" and the lyric text in tab delimited format.  This is a very simplistic lyric format, only being slightly more capable than the simple LRC format in that the simple LRC format does not define lyric duration.  Some suitable editors for this format include VividLyrics Editor and rokudaime19's developmental Lyric Editor (http://www.fretsonfire.net/forums/viewtopic.php?f=11&t=30829).
Vl-
	VL is the native file format for the VividLyrics Editor (http://www.vividlyrics.com/download.htm), which has a very capable and easy-to-use interface for creating syllable, word or line-synced pitchless lyrics.  It has seamless controls for inserting "sync points" that tie specific parts of the lyrics with specific parts of the song, has a waveform display of the audio, various keyboard shortcuts, support for 3/4 and 1/2 speed playback and various other features for fine-tuned editing.  This format is unique in that the timing resolution is fixed at 10ms instead of being as granular as 1ms.
Midi-
	The scrolling, pitched lyric format used by Rock Band, and subsequently, newer versions of Frets on Fire (such as "FoFiX").  This format is similar to the KAR variant format and is much more complex than many due to the use of the Simple Midi File specification,  using a vastly different timing format than script style lyrics.  Converting to this timing system introduces a very small potential for timings to be rounded up or down in a way that can differ from the original timing by increments as small as one millisecond.  Otherwise, the timing system is very accurate and supports an indefinite number of tempo changes.  Some Rock Band MIDI files may even contain harmony vocal tracks in addition to lead vocal tracks, such as those in Rock Band: Beatles, and potentially others.  The general components of this format:  Note 105/106 On/Off to mark the Start/Stop of lines of lyrics, a Lyric event followed by a Note On and Note Off to represent a lyric, its pitch and its start and stop positions and Note 116 On/Off to mark the Start/Stop of an overdrive vocal phrase.  The documented range of vocal notes used by this format are 36 through 84 (C2 through C6).  This program also has the ability to import a MIDI that contains Lyric events but is missing the corresponding pitch definitions.  This will cause them to export back to MIDI without the Note On and Off events, but they will exported as freestyle when exporting to UltraStar or Vrhythm format.  There is a variant which enclosed a Standard MIDI File inside an RIFF header to make it a RIFF compliant file.  Such a file is called RIFF MIDI, also known as RMID.  A typical extension for this type of file would be .rmi instead of .mid.  This converter supports both standard MIDIs as well as RIFF MIDIs.  Also, Rock Band Audition (.rba) files contain audio and chart data.  This program supports importing the midi from a RBA file.
Ustar-
	This is the text format used by UltraStar (and variants such as UltraStar Deluxe).  UltraStar is a clone of the video game SingStar, a multiplayer Karaoke game with support for background video.  The timing of this format is unique in that it requires the starting timestamp and duration of each lyric to be defined in quarter-beats, each unit of which is one fourth of one beat as per the specified tempo.  The basic format for each lyric entry is the following components separated by whitespace:  lyric style, timestamp (in quarter beats), duration (in quarter beats), pitch and the lyric text.  This format may possibly support tempo changes, but the UltraStar community only recommends using a single tempo due to scarce support in the UltraStar (and variants) game for tempo changes, and the FoF Lyric Converter will only export this format with a single tempo.  It is for this reason that lyric timing has a moderate potential for skew due to the relatively low level of precision this increment of measurement allows with lower tempo values.  The best way to reduce loss of timing is to specify a high tempo using the -bpm parameter to manually define the tempo used or by using the -brute parameter to automatically select the most accurate tempo out of a predefined, recommended range.
	To export Rock Band vocals to a format usable in UltraStar:
	1.  Import the Rock Band midi and export to "ustar" for UltraStar
	2.  Use an audio editing utility such as Audacity to merge the multiple OGG audio files.  In Audacity:  Open one of the chart's OGG files.  Then open the File menu, select Import, and select Audio, opening another of the audio files for the same chart.  Repeat this process for each of the audio files contained in the chart (ie. charts may have a total of 4 audio files: guitar.ogg, drums.ogg, rhythm.ogg and song.ogg, so 3 audio files would have to be imported after the first file was opened).  Once all audio tracks have been loaded, open the File menu, select Export and select a name and destination to save the file into (make sure not to overwrite other files on accident).  You can save in either MP3 or OGG format and can optionally use the "Options" button in the Export File menu to change quality options.  It may prompt you to enter tag information, which is completely optional.  It should mention that "Your tracks will be mixed down to two stereo channels in the exported file" unless you disabled the message or are using a version of Audacity that doesn't produce this warning.  This message indicates that the several audio files will be merged into a single file when it is saved, which is what we want.  Saving the new audio file to the place where you exported your UltraStar file would be a good idea, as the audio file for the lyrics has to be in the same folder as the UltraStar file.
	3.  Open the exported UltraStar file in a text editor.  Edit the text after "#TITLE:" and "#ARTIST:" to the Title and Artist for the song, respectively, and copy+paste the filename for the audio file after the colon on the line that says "#MP3:".  This filename cannot include a folder path as the file is expected to be in the same folder as the UltraStar file.  You shouldn't need to edit any other parts of the file unless you want to change the lyrics for a bit of fun.  You can also add a picture to display during song selection (similar to how FoF does) by saving a JPG format picture into the same folder as the UltraStar file.  Then insert a line at the top of the UltraStar text file that begins with "#COVER:" and copy+paste the name of the JPG file after the colon.  I have noticed that after adding a new song or a cover picture, you may need to restart UltraStar before it notices the change.
NOTE:  UltraStar format only allows for one vocal style at a time, so a lyric cannot be both freestyle and overdrive in this format.  During UltraStar export, lyrics that are both styles will export as freestyle.
Lrc-
	LRC is an older lyric format that prefixes each line of lyrics with a timestamp in the format [mm:ss.xx].  This format does not contain durations or pitches, and is one of the less desirable lyric formats.
Elrc-
	Extended LRC is an improvement over the original format in that timestamps may be inserted within a line of lyrics, providing the capability for syllable-synced accuracy.
Vrhythm-
	This is a format that was proposed to me, containing the combination of a MIDI file with vocal timings (or rhythm) and a pitched lyric text file containing a vocal pitch and a lyric for each vocal rhythm note in the MIDI file.  Each vocal rhythm note in the MIDI file is placed to mark the beginning of a sung syllable, and has a length corresponding to the length of that syllable.  The vocal rhythm notes may be of any fret 1 through 5, but must be located within a single instrument and a single difficulty.  The MIDI instrument track and difficulty that contains the vocal rhythm for import is specified in the first line of the pitched lyric file in the format "midi = (INSTRUMENT)(DIFFICULTY #)".  The instrument track identifiers are CASE INSENSITIVE and are as follows:
	G	PART GUITAR (the guitar track)
	B	PART BASS (the bass guitar track)
	C	PART GUITAR COOP (the "Lead Guitar" track)
	R	PART RHYTHM (the rhythm guitar track)
	D	PART DRUM or PART DRUMS (the drum track)
	V	PART VOCALS (the vocal track)
	The difficulty numbers are:  1 (SupaEasy), 2 (Easy), 3 (Medium) and 4 (Amazing).  In some versions of FoF, such as FoFiX, Rock Band difficulty names are displayed instead (Easy, Medium, Hard, Expert).  So to denote that the import vocal rhythm MIDI has the vocal rhythm in the Expert Drum section, the first line of the pitched lyric file should read "midi = D4" (without quotation marks).  The rest of the pitched lyric file should contain the lyric and either the pitch or note name of each vocal rhythm note charted in the MIDI, one lyric and one pitch per line.  The syntax for each pitched lyric is the pitch, followed by whitespace, and the text for the lyric.  When denoting the pitch using numbers, valid numbers range from 0 (C in the lowest octave of -1) to 127 (G in octave 9), with middle C being 60 (C in octave 4).  Follow this chart as a reference:  http://www.harmony-central.com/MIDI/Doc/table2.html.  Alternatively, you can specify the note name in the following syntax: (NOTE NAME)(OPTIONAL SHARP CHARACTER # or OPTIONAL FLAT CHARACTER b)(OPTIONAL OCTAVE NUMBER).  For example:  F#-1, A, Db3, C4.  If no octave is given, middle octave (4) is assumed.  Technically, a sharp note could be the same as a different flat note.  The distance between one note to the next is measured in "steps".  Some of the music note letters have a "semitone" (AKA half step) between them, going in this order:
	C  C#  D  D#  E  F  F#  G  G#  A  A#  B
So Db (D flat, which is one half step below D) is the same note as C# (C sharp, which is one half step above C).  Strictly speaking, there is no half step between E and F and between B and C, these notes are considered to be a half step away from each other instead of one full step away like the other notes.  Even so, I have seen sheet music that wrote key signatures in a way that would reference these non existent notes (like C flat), so the program will be lenient and simply increment the pitch for a sharp note and decrement the pitch for a flat note.  Thus, entering Fb will essentially be equivalent to entering E, and entering B# will be the same as entering C in next octave up.  Follow this graphic as a reference for getting the note name and octave when reading sheet music:  http://www.dolmetsch.com/namingoctaves.gif.  This readme isn't meant to be a primer on music theory, so use your favorite Wikipedia article, music website, etc. to find out more about reading key signatures, which define which notes are flat or sharp on a piece of sheet music.  When a syllable is an INCOMPLETE word, it should be followed by a hyphen to indicate that the next lyric is a continuation of the previous word.  Do note that a pitch shift is not considered a syllable, so if "starstruck" was to be sung with three syllables, you would chart the lyrics as "star-" "+" "struck".  The hyphen from the first syllable applies to mean that the second syllable "struck" is part of the same word.  The + lyric just means that the first syllable changes pitch.  If you use a pitch shift and there is no syllable that follows, do not put a hyphen at the end of the lyric that precedes the pitch shift, or it could cause the next word to incorrectly group.  For example, "can-" "+" "have" would end up causing the three lyrics to import as "canhave" instead of "can have".  Use an empty line with a hyphen to denote the separation of one vocal phrase from another.  Once the final vocal phrase has been completed, there doesn't need to be a hyphen to end it, the file can be saved and closed.  An asterisk can be placed after the hyphen to denote that the next phrase will be vocal overdrive.  Following documented Harmonix recommendations, the entire vocal phrase (line) is marked for overdrive.  For a lyric that is pitchless (ie. rap or speech), replace the pitch with a pound symbol.  An example of accepted lyrics:
	midi = C1
	50 lyric
	# spoken lyric
	-*
	43 OV-
	45 ER-
	57 DRIVE!
	43 +
	-
	C# This is mid C, sharp (MIDI note 61)
	Eb-1 This is E in the lowest octave, flat (MIDI note 3)
	F#9 This is F in the highest octave, sharp (MIDI note 126)
	33 etc.
	The success of using this input format necessitates that there are the same number of entries in both the vocal rhythm and pitched lyric files.  If the vocal rhythm file has more entries, the excess entries will be given a generic pitch and the lyric will read "*".  If the pitched lyric file has more entries, the excess entries are ignored and a warning is generated.  One way to avoid this problem is to create the vocal rhythm MIDI first, import it with this program by supplying the vrhythm track identifier instead of a pitched lyric file and export it to vocal rhythm format (specifying a different MIDI file to save to, which can be discarded).  The result will be that the pitched lyric file that is created will have the correct number of entries, allowing you to just enter the correct pitch and lyric for each entry.  If you chart the vrhythm notes so that the first vrhythm note in each line of lyrics use one fret (ie. fret 2) and all other lyrics in that line collectively use a different fret (ie. fret 1), exporting lyricless vrhythm will insert line breaks accordingly, making it easier to chart vocal rhythm.  When pitched lyrics are exported, a line phrase is only marked for overdrive if the first lyric in the line is marked for overdrive in the imported lyrics.
Skar-
	Officially, the KAR (Soft Karaoke) format was created by Tune 1000 Corporation, who discontinued its use.  Since then, the format and variants have been created and distributed to the point where KAR is commonly used to refer to any MIDI file that contains timed lyrics.  The official Soft Karaoke format stores some tag information in a MIDI track called "Soft Karaoke" and stores lyrics as Text events in a MIDI track called "Words".  These lyrics only have the starting timestamp indicated by the Text events' positions and do not contain vocal pitches, styles or durations.  The definition of the lyrics allows for partial words to be indicated based on spacing on either side of the lyrics, so the duration of a partial word lyric can be derived based on the starting time of a following part of the word.  The duration of all other lyrics would need to be defined manually, as this information is not available in the "Words" track.
Kar-
	Unofficial KAR variants typically use one of the MIDI tracks (ie. a track called "Melody") to store the lyrics as Text or Lyric events, with a Note On and Note Off event for each lyric to represent vocal pitch and duration.  This is generally similar to the way that Rock Band MIDIs store vocal information.  The main difference between KAR and Rock Band MIDIs is that vocal phrases in KAR files are seperated by a lyric event containing a formatting character such as a carriage return or newline character, and there are no defined vocal styles.
ID3-
	An ID3 tag is a set of information that can embedded in audio files such as MP3s, storing song information such as artist, song title, etc. in pieces of information called "frames".  It's common for these ID3 frames to be referred to as "tags" instead, although this is technically incorrect, as there can only be one ID3 tag (of each version) defined in a file.  Among the information that can be stored in an ID3 tag, synchronized lyrics may be defined in a "Synchronized Lyrics" frame, which has a header string of "SYLT".  This kind of lyrics is very similar to LRC, which can support line/word/syllable synced accuracy depending on the creation of the file.  However, this format is less accurate than Extended LRC in that only one timestamp per lyric entry is allowed, so it cannot store lyric durations.  It also cannot store lyric styles.  When importing ID3 lyrics, this program cannot make many assumptions about the lyric durations, they will be given the duration of 1 millisecond unless there is some other means to assume a longer duration (such as when a lyric groups with another).  Something else that makes the ID3 synchronized lyrics format unique from LRC format is that besides storing lyric timestamps in milliseconds, it can instead store them in units of "MPEG frames".  Various websites, programs and even one or more published books incorrectly define the duration of one MPEG frame as 26.1ms.  This is not only of low accuracy, but it makes assumptions of the mpeg version, layer and sample rate, all of which are key components in finding the actual duration of one MPEG frame.  For those interested, the REAL formula for determining this duration in milliseconds is as follows:
	samplesperframe * 1000 / samplerate
The number of samples defined in one MPEG frame is always 384 for "layer 1" MPEG files and is always 1152 for "layer 2" or "layer 3" MPEG files (MP3 files are MPEG1-Layer 3).  The sample rates that are supported depend on which MPEG version the file is:  MPEG 1, MPEG 2 or MPEG 2.5.  MPEG 2.5 is not a real standard, it's more or less experimental.  So for MP3 files sampled at 44.1KHz, the correct duration of one MP3 frame is roughly 26.12ms.  I have tested the MiniLyrics program, and although it supports loading Extended LRC lyrics, it will only embed Simple LRC quality (line synced) lyrics into the specified MP3 file even if the lyrics were defined to be syllable synced.  I have contacted their support for clarification, and the program intentionally lowers the accuracy of the lyrics to maintain compatibility with deficiencies in the way Windows Media Player displays SYLT lyrics.  As this program will export the lyrics in the same level of accuracy as the source lyric file, keep in mind that some software may not correctly read them, due to problems with their programming.  In order to emulate the line accuracy of MiniLyrics (if you desire it to work in afore-mentioned faulty programs), you can try exporting the lyrics to ID3 format with line grouping enabled (ie. foflc -in vl Lyrics.vl -out id3 inputmp3.mp3 outputmp3.mp3 -grouping line).  If the import and export formats are both ID3, you can skip specifying the source MP3.  For example:
	-in id3 file1.mp3 -out id3 file1.mp3 file2.mp3
will perform the same conversion as:
	-in id3 file1.mp3 -out id3 file2.mp3
When the source MP3 is not manually specified, the input file is assumed as the source file.  If using different MP3 files for the input and source file, or if the input format is not ID3, you must always specify the source file to perform ID3 export with.  A MPEG audio file is allowed to have both an ID3 version 1 and an ID3 version 2 tag, and this program writes both ID3v1 and ID3v2 tags to store information in the output file.  Any song information (such as Artist, Album, Title, Year) that exists in the input file will override equivalent information in the source MP3 file's ID3 tags and will be saved in the output file's ID3 tags.  If there is conflicting information in the input MP3's ID3v1 and ID3v2 tags, such as if both define a different artist, the information in the version 2 tag is used.  Any other ID3v2 frames that exist in the source MP3 file will be copied to the output file.
SRT-
	This is a  format that is commonly used for line-synced subtitles.  Each subtitle entry has a start and stop time in milliseconds.


OPTIONAL PARAMETERS:
--------------------
======
OFFSET -
======
	Optionally, the offset parameter will subtract # milliseconds from the beginning of all imported lyric timestamps, which is useful for synchronizing the input lyrics with the chart.  The offset given may be positive or negative (providing a negative offset will cause the timestamps to be increased by the specified number of milliseconds).  By default during MIDI import, this program loads the offset from song.ini if it is present in the same folder as the imported MIDI.  This parameter can be used to override the value in song.ini or provide the appropriate delay if song.ini is absent.  The correct offset number to specify should be the number that follows "delay =" in the chart's song.ini file.  This is necessary if your chart has a delay value that is not 0, as FretsonFire adds this delay to the beginning of chart's playback once the song's audio is started.  This is by design, allowing the game to synchronize the audio with the chart.  If you do not provide foflc the chart's offset to compensate for the delay, the lyrics will not be synchronized with the chart and will display early or late.  Certain formats such as VL store their own offset parameter, which is read and used by foflc unless an offset is defined manually with "-offset".  "-offset 0" could be used to override the delay in a vl file and effectively eliminate it.  If you want to sync pre-existing lyrics with your chart instead of syncing lyrics you made yourself, consider using the starstamp parameter detailed below.  Likewise, if a source MIDI is imported, the song.ini file is read from the directory that contains the source MIDI, but that offset would need to be overridden by the SRCOFFSET parameter described below, as the OFFSET parameter only influences the offset of the lyrics imported with the IN parameter.
=========
NOHYPHENS -
=========
	Optionally, the nohyphens flag will control how trailing hyphens on imported lyrics are handled.  By default, foflc will append a hyphen at the end of a piece of lyric if it ends within the middle of a word.  For example, a vl file may have timing defined for each syllable in the word "Barracuda", breaking it into "Ba" "rra" "cu "da".  foflc would then, by default, separate each of the syllables so that the exported lyrics for the word are "Ba-", "rra-", "cu-", "da".  No hyphens are inserted in this way for RB MIDI lyrics that are imported, as they already are required to end in a hyphen if they are a part of an incomplete word.  Hyphens may be inserted in KAR or Soft Karaoke lyrics, which use spacing at the beginning or end of the lyrics to define whether it is a partial word lyric.
	If "-nohyphens 1" is specified, hyphens are not inserted into the input lyrics even if the imported lyrics designate that a lyric is a partial word.  If the input lyric file is a Rock Band midi, the lyrics contained within should already have hyphens appended to the end of pieces of each partial word lyric.  For the above example, using "-nohyphens 1", the syllable synced lyrics for "Barracuda" would be exported as "Ba" "rra" "cu "da" without the appended hyphens.  Currently, VL, UltraStar and LRC imports will insert hyphens accordingly unless this behavior is suppressed.
	If "-nohyphens 2" is specified, existing trailing hyphens are suppressed from the lyrics so that if the input lyrics contained "par-" "a-" "noid", such as in a Rock Band format MIDI, the exported lyric would be "par" "a" "noid".
	If "-nohyphens 3" is specified, hyphens are not inserted into the exported lyrics and existing hyphens at the end of individual pieces of lyrics are suppressed.
	If "-nohyphens" is specified without a number parameter, "-nohyphens 3" is assumed.
	!Please note that if a midi or script file is exported with the hyphens removed, the hyphen placements are lost permanently, because these formats do not use any other method to keep track of whether a piece of lyric is less than an entire word.  This will cause those lyrics to have no way to automatically regroup syllables into words.
======
NOPLUS -
======
	Optionally, the noplus parameter will control how pieces of lyrics are handled if they consist only of a plus sign.  Rock Band midis are designed to use these + signs to signify that whoever is singing needs to change pitch while still singing the same syllable that they currently are singing.  If "-noplus" is specified, these plus signs are not exported as individual lyrics, but their duration is included in the preceding syllable so that it retains the correct duration.  The pitch of the "+" lyrics are discarded.  For example, using this parameter, the two lyric events "Cake" and "+" would import as "Cake", which has the duration of both lyrics but the pitch of the imported "Cake" lyric.  Please note that if a midi file is exported with the plus signs removed, the plus sign placements and pitches are lost permanently, because the Rock Band/FretsonFire midi format does not use any other method to track pitch shifts.
=========
MARKLINES -
=========
	Optionally, the marklines parameter retains line markings during script export, allowing the line grouping to be performed on the exported script file if it is imported at a later time.  This is obtained by inserting comment lines into the output file, and allows lyric formats to be exported to script format and back without losing the line placements.  For word grouping to work for imported scripted.txt files, partial words must end in a hyphen.  This parameter is unlikely to cause any problems during playback in FoF, but it's possible that some versions of FoF may not handle it correctly.  This parameter is only usable when the output format is Script.
========
NOLYRICS -
========
	Optionally, the nolyrics parameter allows for the requirement of lyrics to be removed from the input file.  Currently, this parameter is only allowed for MIDI and KAR imports (but it can be used for Vrhythm import by specifying the vocal rhythm instrument track identifier instead of a pitched lyric file), and allows a MIDI or KAR file to be imported even if the imported track contains no appropriate lyrics.  The exported file contains an asterisk with each pitch that was encountered in the input MIDI track.  If a chord is encountered, only the first note of the chord defined in the MIDI or KAR file is kept and all other notes in the chord are dropped.  This is intentional, because any backing vocals pitches belong in a different track.
========
GROUPING -
========
	Optionally, the grouping parameter will control the separation of words and partial words during export.  By default, foflc will not combine partial word lyrics in any way, they are exported as they exist in the imported lyrics.  The grouping parameter allows individual words to be grouped into whole words, or words to be grouped into entire phrases.  For example:
	If "-grouping word" is specified when importing a midi file that contained the lyrics "Ap-" "er-" "ture" "Sci- ence", they would be exported as "Ap-er-ture" "Sci-ence".  Grouping could be combined with the nohyphens parameter to export it as two words: "Aperture" "Science".
	If "-grouping line" is specified when importing a midi file that contained the lyrics "Hang" "on" "to" "the" "glo-" "ry" "at" "my" "+" "right" "hand", they would be exported as "Hang on to the glo-ry at my + right hand".  Grouping could be combined with noplus and nohyphen to export it as "Hang on to the glory at my right hand".  Script style lyrics that were created using the marklines parameter described above can be imported and exported with line grouping, whereas normal script lyrics cannot.
=======
VERBOSE -
=======
	Optionally, the verbose parameter will output informational logging to the screen.  Alternativly, the debug parameter outputs much more information to the screen, which will be useful to help troubleshoot a file that will not import.  For example, if you see that output shows the program exits before completion of a MIDI file, you can load the MIDI in a hex editor and go to the last MIDI event address specified to examine the problem.  Since your command window probably won't let you scroll to see all of the verbose output, you can use the output redirector on the command line to save the screen output to a file and look at it.  For example:
		foflc -in midi notes.mid -out script script.txt > output.txt
	If you want to append the output to a file without deleting the original file, you can use the append output redirector:
		foflc -in midi notes.mid -out script script.txt >> output.txt
	Text that is output to the "stderr" error output stream (displays on screen, but in a different manner), you need to use an additional redirect command if you want that saved to a file:
		foflc -in midi notes.mid -out script script.txt > output.txt 2>&1
	The "2>&1" redirects error output to the normal screen output stream (stdout) and the first ">" redirects the "normal" screen output to the file.  You must put the error stream redirector last or it will not work.  This parameter may not be used simultaneously with the debug parameter.
=====
DEBUG -
=====
	Similar to the verbose parameter, but includes much more logging information.  This parameter may not be used simultaneously with the verbose parameter.  Output redirection is generally a must with this parameter, especially for MIDI import, which logs ENORMOUS amounts of text.
======
FILTER -
======
	Optionally, the filter parameter allows a defined set of characters to be removed from the end of lyric pieces.  If a character set isn't defined, ^%#/ is assumed.  The filter can't contain space, alphanumerical, +, - or = characters.  For example, if you are converting RB lyrics to script.txt and you don't want those ^ characters, you can either use the default filter list by using "-filter" with no parameters, or if you wanted to keep the other special characters, you chould single ^ out by using "-filter ^".  It's important to note that since these special characters are placed after hyphens in partial words, you may need to use filtering in order to ensure that the hyphens are removed from the ends of all lyrics pieces if you are using the "-nohyphens" parameter.
=====
QUICK -
=====
	Optionally, the quick parameter will skip as much MIDI processing as possible during MIDI import, skipping to the next MIDI track if it find the currently-processed track is not the import vocal track (ie. "PART VOCALS" by default for MIDI import).  This will cut down the amount of time it takes to process the vocals by a substantial amount, not that it took very long to begin with.  It is more useful to cut down on the logging that is generated, so that there's less log to look through for troubleshooting.  More importantly, if there are MIDI violations in a track besides the one from which lyrics are being imported, it will allow the program to skip over them and finish cleanly (although you should be warned that continued use of a nonstandard MIDI file may cause you problems later on).  Unfortunately, it's not feasible for me to pro-actively handle all MIDI violations that some files may have, and if the import MIDI track has issues that cannot be handled, the program will abort.  This parameter is only usable when either the input or output format is MIDI, Vrhythm or KAR.
==========
STARTSTAMP -
==========
	Optionally, the startstamp parameter will allow the timestamp of the first lyric to be defined manually, keeping the relative timing for all other lyrics the same.  This is the easiest way to use an existing lyric file that was created for the same song recording, but having a different amount of silence at the beginning than the audio file that you are using.  For example, if you found timed lyrics for the album version of a song, and you have the same album version of the song for your chart, but you cut off some of the leading silence from the song, find the starting time of the lyrics in your song (in milliseconds).  This is relatively easy by using any kind of program that lets you slow audio playback and stop/start playback easily, especially if the program draws the audio file's wave form for you (Audacity and the VL Editor are very good for this purpose).  So say you had cut off silence before you began charting the song and determined that the first lyric begins at 15000ms, instead of using the offset parameter and calculating the time offset you need to use, supply the parameter "-startstamp 15000" when using the converter to re-sync the lyrics.  All exported lyric timings will be relative to the first timestamp, so if you used the same recording that was used for the imported lyrics, the lyrics will now be synced to your exported lyrics because the only difference between the two audio files is the amount of silence at the beginning.  This does, of course, rely on the quality of the imported lyrics and the accuracy of the timestamp you provide.
	! Do note that you cannot use the offset and startstamp parameters simultaneously because they both modify the timestamps of the imported lyrics.
===
BPM -
===
	Optionally, the bpm parameter will allow you to specify a tempo for the output file (originally for UltraStar export, but can also be used when exporting Vrhythm, KAR or MIDI if a source MIDI file is not provided).  Define the tempo via the command line as just a number, such as "-bpm 800".  The value specified must be at least 2 (2BPM), but either a whole number or a partial number (such as 350.25) may be given as the tempo.  If the export format is UltraStar and this parameter is not specified, the program will estimate a tempo based on the imported lyrics, unless the import format is also UltraStar, in which case the tempo from the import file is used during export.   To prevent performance problems caused by having too high of a tempo, the UltraStar community recommends not specifying a tempo of higher than 400BPM.  However, from my testing, I found that a decent computer should be able to play a song in UltraStar that has a tempo of 800BPM or higher.  My findings are that a tempo of 800BPM provides very good accuracy despite converting between very different timing formats.  If the export format is MIDI, KAR or Vrhythm, and there is no source MIDI provided, the exported file is given a default tempo of 120BPM.  If a source MIDI is given, the tempo events in that MIDI are used for the export MIDI.  This parameter may only be used for UltraStar export or a MIDI based export (if no source MIDI is given).
=====
BRUTE -
=====
	Optionally, the brute parameter finds the best tempo for Ultrastar export.  This is achieved by calculating the timings for each tempo between 200BPM and 400BPM in increments of 0.01BPM and utilizing the tempo that has the overall least time skew compared to the original timing of the imported lyrics.  This parameter is only usable when the output format is UltraStar.
====
HELP -
====
	Use of the help parameter will cause program syntax and information to be displayed and will half any import or export describe by the rest of the parameters that are given.
=========
SRCOFFSET -
=========
	Optionally, the srcoffset parameter allows the lyric timing for the source file to be offset manually, such as to override what is read from song.ini.  Conceptually, this is to offset the lyric timing during export (as opposed to during import, which the offset and startstamp parameters are for).  Normally, I expect that the only reason to do this is to import a MIDI and merge it with a different source MIDI in the same folder that does not have the same MIDI delay as the import MIDI.  Since any existing song.ini is processed to load the MIDI delay during any MIDI import or source MIDI import, srcoffset and offset may be used to control any offset applied to the lyrics during import and before they are ultimately exported.  This parameter may only be used when a source MIDI is provided (for MIDI or Vrhythm export).
=======
INTRACK -
=======
	Optionally, the intrack parameter allows the track containing the lyrics to import to be manually defined.  For example, specify -trackname "PART HARM1" to import the first harmony track's vocal information from a Rock Band:Beatles MIDI.  The track name must be enclosed in quotation marks if it contains whitespace and is NOT case sensitive.  This parameter may only be used for MIDI or KAR import.  This parameter may not be used for Vrhythm import, as the imported track name depends on the Vrhythm IDentifier given.  This parameter may not be used for Soft Karaoke import, as the imported track name is pre-determined.
========
OUTTRACK -
========
	Optionally, the outtrack parameter allows the track that will be written to export the lyrics to be manually named.  If not specified, the default track name used during MIDI export is "PART VOCALS".  This parameter may only be used for MIDI export.  This parameter may not be used for Vrhythm export, as the exported track name depends on the Vrhythm IDentifier given.  This parameter may not be used for Soft Karaoke export, which uses predetermined track names.
=========
NOTENAMES -
=========
	Optionally, the notenames parameter may be used for Vrhythm export to have the vocal pitches be written as note names instead of note numbers.  For example, note number 106 will be written to the pitched lyric file as A#7.  This is reciprocal to the ability to import pitched lyrics that use note names instead of numbers.  This parameter may only be used for Vrhythm export.
========
RELATIVE -
========
	Optionally, the relative parameter may be used for UltraStar export to save the lyrics in relative timing instead of the default absolute timing.  In relative timing, each line break in the UltraStar file causes the timestamp to reset to 0.  I have tested conversion between relative and absolute timing with this program, and timestamps are kept accurately, but the durations of lyrics have a possibility of rounding up or down.  This is probably the fault of integer math and may change one day if I decide to use floating point number storage.
=======
NOPITCH -
=======
	Optionally, the nopitch parameter may be used for MIDI export to suppress the generic vocal pitches that are saved if the import lyrics had no pitch information, such as converting from VL to MIDI format.  This would result in the exported MIDI having no vocal pitches, and subsequently no lyric durations, as that is the only mechanism used to store duration.  Notes 105 and 116 are still written to the exported MIDI to mark line phrases and overdrive phrases.  If a MIDI or pitched lyric file is imported that is missing some or all of the vocal pitches for lyrics, -nopitch will cause such pitchless lyrics to export without a generic vocal pitch.
======
DETECT -
======
	Optionally, the detect parameter may be given instead of an input and output format.  This will perform a lyric detection of the specified file and print the detected format to the screen.  All lyric formats except for Vocal Rhythm MIDI can be detected.  If a detection is performed on a MIDI based file that contains multiple types of lyrics (ie. both KAR and SKAR), all lyric format matches and the track names for each will be given.
======
ID3TAG -
======
	Optionally, the id3tag parameter may be given instead of an input and output format.  This will read the ID3 tag of the specified file (ie. MP3, but other files that have a valid ID3 tag should also work) and display all of the "Text Information" frames (ie. Artist, Album, Year, etc.) to the screen.  Currently, only ASCII (ie. English) text can be interpreted.  Any tag information using Unicode text will be skipped.
========
NOSRCTAG -
========
	Optionally, the nosrctag parameter prevents existing content from the source file's ID3v2 tag from being copied to the exported file.  If used without specifying specific frames, all ID3v1 and ID3v2 content from the source MP3 is left out of the output MP3.  This could be used to ensure that the output file has nothing in the ID3 tag besides the synchronized lyrics and tag information from the input lyrics.  Otherwise, this parameter can be called with multiple frame IDs, such as:
	-nosrctag apic TIME tcon
Case shouldn't matter, but note that you cannot call nosrctag multiple times, mixing it with specific IDs and with no IDs (using it as a wildcard).  For a list of ID3v2 frame IDs, you can consult the ID3 3.2 informal standard website (http://www.id3.org/id3v2.3.0).  If artist, title or album tag information is obtained from the input file, those ID3v2 frames are written during ID3 export and those frames are automatically omitted from the source MP3, so they needn't be manually specified to be excluded.  This is by design because writing multiple artist frames would violate the ID3 standard.  During ID3 export, any existing SYLT frame in the source MP3 is always excluded, and the imported lyrics are used to write a new SYLT (synchronized lyrics) frame.
========
NOFSTYLE -
========
	Optionally, the nofstyle parameter prevents the automatic addition of the pound character (#) freestyle indicator when exporting freestyle or pitchless lyrics to MIDI format.  Converting VL format to Rock Band MIDI format with this parameter, for example, will result in a MIDI with all lyrics containing an identical generic pitch and no freestyle indicator.  This should work around an issue where some versions of FoF may improperly display vocal modifier characters like the pound character instead of hiding them when displaying the lyrics in-game.  The drawback of using this work-around is that the vocal track itself won't be suitable for playing because they won't score as freestyle lyrics.  If the lyrics that are converted with this parameter are freestyle/pitchless, you can import the resulting MIDI and export back to MIDI without nofstyle in order to restore the freestyle characters.  This is because the program automatically treats the imported lyrics as freestyle if all of the pitches are the same.


OTHER NOTES:
------------
-The specified input and output files are not allowed to be the same, to prevent accidental overwriting.  If exporting a midi file, the source midi file name is not allowed to be the same as the output file name because part of the source file must be read into the output file.
-Filenames may not begin with a hyphen, even when enclosed in quotation marks (ie. "-notes.mid" is not accepted)
