User Guide
Release
Copyright January 2003
by
John Edwards
CONTENTS
The purpose of this guide is to assist in the use of oggdropXPd. No attempt is made here to explain the principles of perceptual audio coding, nor the inner workings of the ogg vorbis codec. All of that information can be gleaned from elsewhere from authors far more knowledgeable than I am on these subjects!
Information on ogg vorbis can be obtained from http://www.vorbis.com/ and on Xiph.Org Foundation from http://www.xiph.org/
The latest versions of oggdropXPd can be obtained from http://homepage.ntlworld.com/jfe1205/
oggdropXPd is a development of the original oggdrop provided as a Windows32 Graphical User Interface to the ogg vorbis encoding libraries from Xiph.Org Foundation.
The functionality in oggdropXPd has been expanded to provide considerably greater control over the encoding options, and also to provide automatic tagging capabilites, and decoding both to file and for direct playback through an installed soundcard.
Options for encoding, decoding, tagging and output directory selection are configured through easy-to-use dialogue screens that are accessed via a menu by right clicking the mouse over the main program window. All dialogue screens can be exited without saving any changed settings either by hitting the cancel button, or the ESCape key on the keyboard.
Encoding is from standard 8 or 16bit PCM wave files, ieee float wave files or uncompressed 'aif' files. In addition, and for convenience, users may also encode from lossless formats: LPAC, Monkey's Audio APE, and FLAC files. In these cases, the files are first decoded to temporary wave files, and then encoded in the normal manner. The temporary file is automatically deleted once it has been encoded. The required 'dlls' are available as separate 'zipped' files for download.
Once the various settings have been configured, processing is achieved simply by 'dragging and dropping' files onto the main program window. The dropping of wave, LPAC, APE and FLAC files will cause the files to be encoded according to the set options. The dropping of 'ogg' files will result in those files being decoded either to file, or played back through the installed soundcard, according to the options selected.
Note: oggdropXPd supports decoding of lossless files. The 'base' version comes with the libFLAC.dll included as support for FLAC decoding is partially integrated within oggdropXPd. The LPAC and MAC dlls are available separately and are only required for decoding files in those formats.
The display also includes details of the proposed encoding settings, quality or bitrate management based. Once encoding commences, the display is altered to indicate the actual average bitrate as encoding proceeds. There is a similar display for decoding.
The items in the first section of the menu, except Set Processing Priority, are dealt with individually, below, the remainder are dealt with here.
Set Processing Priority reveals a sub-menu that offers the four options indicated above. The default selection is NORMAL Priority, although on most modern processors, IDLE Priority is sufficient. Although included, REALTIME Priority is not recommended and should be avoided. Simply check the priority you require.
Stop Encoding and Stop Decoding do precisely as indicated, if checked, they interrupt and stop processing. They also remove the current and any outstanding files from the list of files to be processed. However, it is the responsibility of the user to delete any partially encoded, or decoded, file. This is not done automatically as it is considered that the partial result may be what is required.
In order to enable the Tagging Setup, it is necessary to check the item - AUTO Tagging. This can be checked either here, or from within the Tagging Setup Dialogue.
Checking Write Log File will result in a log file being written as encoding proceeds. The log file is called oggdropXPd.log, and is a standard text file. It contains information concerning the input and output files and the encoding parameters. The following is an example, but depending on the parameters selected for encoding, other information may also be provided.
***********************************
07/01/2003 - 12:45:34
Input filename: D:\MyMusic\Enigma\Love Sensuality Devotion-The Greatest Hits\04-T.N.T. For The Brain.wav
Output filename: D:\MyMusic\Enigma\Love Sensuality Devotion-The Greatest Hits\04-T.N.T. For The Brain.ogg
Output filesize: 7954224 bytes
No. of Channels: 2
Sampling Rate: 44100Hz
Total Samples: 14020860
Length: 317 seconds
Quality setting: 6.25
Average Bitrate: 200.1kbps
By default, Show Bitrate is checked and causes the encoding bitrate to be displayed in the main program window. This may be unchecked if you don't wish it to be displayed.
Also by default, Always on Top is checked. This may be unchecked if you so wish.
And, finally, select Exit when you have completed all your current encoding/decoding needs!
The Encoding Options Dialogue provides a comprehensive means to configure the encoder.
It is recommended that Quality Management Mode is used in preference to Bitrate Management Mode as this provides consistently higher quality results. Bitrate Management Mode is provided to allow stricter control over encoded file sizes where this is a critical factor. Most users should use the Quality Management Mode for their normal encoding requirements.
Quality Management Mode provides a simple means of selecting the Quality Setting to use. The settings range from -1.00 to 10.00 and can be set either by the scroll bar, the left and right cursor keys on the keyboard (once the ScrollBar has the focus), or by entering the chosen setting directly in the Quality Setting box. Whichever method is used, the narrative to the right of the Quality Setting box will indicate the Nominal Bitrate that will be used for encoding assuming an input file of 16bit 44.1kHz stereo PCM data. The actual bitrate of the encoded file will depend very much upon the nature of the material to be encoded and the ease or difficulty with which it can be encoded while maintaining the required quality.
Bitrate Management Mode provides the option to select Average BitRate, or Constant BitRate encoding. In general terms, ABR is less strict about the target bitrate and is set using the Nom. Bitrate box in Bitrate Management Options. Ogg Vorbis does not offer true CBR encoding, an emulation is provided that comes very close. This method should be used ONLY when the strictest control over encoding bitrates is required. In ABR mode, Min. Bitrate, Nom. Bitrate and Max. Bitrate boxes are used to define floor, mean and ceiling bitrates.
Checking Delete input files after encoding will result in input files being permanently deleted following completion of encoding. Selecting to stop encoding or decoding with this option enabled will NOT cause the current partially encoded/decoded input file, or files remaining on the input list, to be deleted. Deletion ONLY occurs upon successful completion of encoding.
Advanced Options covers other areas where control can be exercised. Check the Downmix Stereo to Mono box to do as it says! By checking the Apply Lowpass box and entering a value in the box between 0 and 22050, your chosen lowpass value will be applied during the encoding process. If you wish to have the material re-scaled during encoding, ie., have the volume decreased or increased, check the box and enter a value in the Apply a Scale Factor of box. This value is a percentage of the existing volume. The range of permitted values is 1.00% - 400.00%. A value greater than 100% will increase the volume and similarly, a value of less than 100% will decrease the volume. The amount by which the volume will be increased, or decreased, in decibels will be displayed in the line beneath the box. And finally, you may select to have the input data re-sampled, up or down, during encoding. The standard default is to encode at the same sample rate as the input data. To change the sample rate, check the box, select the new sample rate from the Re-sample to: box and then check the Use for this session only box if you do not want this rate to be set as the new default.
Once your selections are complete, click the Accept button to make them effective. You may abandon your changes by simply closing the dialogue without clicking the Accept button.
The Decoder Options Dialogue provides the means to configure the decoding of ogg files.
Mode offers the primary selection of either Decode to File or Playback, check whichever you require. Checking Playback will remove all Output Wave Format Options except 16bit PCM. Decode to File enables all output options.
Decoder Settings allows you to choose to have the output dithered, with or without degrees of Noise Shaping by checking and selecting the relevant option. Additionally, you may select to Apply 6dB Hard Limiter which will apply a smoothed roll off to peak scale rather than a crude compression at peak scale. Where the input ogg files have been tagged with VorbisGain Tags, you can choose to have these tags read and applied during the decoding process by selecting the required option. In addition to having the output volume adjusted via the VorbisGain Tags, you may also apply a volume adjustment via Pre-Amp Settings in 0.1dB steps between -12dB and +12dB. The Pre-Amp Settings will be applied cumulatively with any VorbisGain adjustments, if selected, or independently if not. Once the required decoding options have been selected, hit the Accept button to make them effective.
To View the Log File, simply select the View Log File option from the Menu. If there is no log file available, a Message Box indicate this fact. The log file is just a simple text file and may also be viewed through any text editor.
You may clear the log file if you wish by hitting the Clear Log button. This will display a confirmation Message Box:
Hitting Yes, will clear the contents of the Log file and hitting No will cancel the action.
Output Directory Options Dialogue
This option requires little explanation. The Standard Default is for output files to be placed in the same directory as input files. However, by checking the relevant option, you may direct output to a different directory for the current session only, or as the default directory. Hitting the button marked '. . .' to the right of the large edit box will allow you to select the output directory to use. If this different directory doesn't already exist, it will be created. Hit the Accept button to make your selection effective.
Temporary Directory Options Dialogue
This option is only available with the version of oggdropXPd that supports lossless decoding. Lossless encoded files are decoded to temporary wave files before encoding to ogg files. The default is for the temporary wave files to be written to the source directory. This option allows the user to select an alternative directory to use for the temporary wave files. This may be particularly relevant if the source files are on read only media.
The Tagging Setup is not as complicated as it may first appear. The style and method of use has been copied from the Monkey's Audio Tagging Setup as it seems quite popular, it works and many people are already familiar with it. Basically, each of the directory/file name master fields may be broken into upto 6 individual fields to be used for tagging and File Renaming. For example, the File Name fields are identified as %1 through %6, the Parent Directory fields are %%1 through %%6, etc. The boundaries between fields are defined by a Separator. The Separator may be of upto 15 printable characters (including the space character) in length. However, when parsing the strings, identificaton of the first 2 characters of the Separator string is interpreted as meaning that we have hit the Separator and characters to the length of the Separator string will be skipped. While the purpose of this scheme is to allow for automated tagging, you are at liberty to enter literal text directly into any the boxes and that text will, instead, be used to form the Tag.
When loaded for the first time, oggdropXPd will create a default GenreData.txt file. This is a simple text file containing a standard list of Genre types. On subsequent occasions, unless the GenreData.txt file has been deleted, the Genre types used for tagging will be loaded from the file. Therefore, once it has been created, you are at liberty to add, delete and amend Genre types as you wish. Note also, that you may type new Genre categories into the edit box and, once the Accept button has been hit, the new Genre will be inserted into the GenreData.txt file. If you don't require a Genre Tag, just leave the Genre box blank.
If you wish to have your files renamed as they are tagged and encoded, check the Rename files on Tag box, and enter some field identifiers, character strings, as you wish in the Filename: box. The same rules apply as for Tagging in terms of how the fields are identified, but you can intersperse the field identifiers with any text literals to have them form part of the filename. You may also place '\', path separators, within the character string you enter. The effect of these will be to have the field identifers and/or the text literals to the left of the path separator used to create a new sub-directory, or sub-directories if more than one path separator has been inserted, with the names formed from the field indentifiers/text literals entered. Obviously, in this instance, the new filenames will then be generated from the field identifiers/text literals that you enter that are to the right of the right-most path separator. There are limits to the permitted lengths of Tags and filename, but it is unlikely they will be exceeded.
If you wish to have a .m3u playlist file added to a directory in the current path, or new path if any new sub-directories have been created using the Rename files on Tag option, check the Playlist on Tag box and enter appropriate field indentifier characters in the Playlist Name edit box. You may enter one '\', path separator, within the string. The identifier(s) to the left of the path separator should evaluate to a (sub-)directory within the path and within the specified hierarchy. Entries in the playlist will be relative to the directory in which the playlist is created.
Important Note: If you have specified the addition of sub-directories within the Rename files on Tag option, the field identifiers will be re-evaluated relative to the new path.
When you are happy with your specified options, hit the Accept to make them effective.
Hitting the Help button will display:
The About Box provides a few useful pieces of information. It will tell you the version of oggdropXPd that you are currently using and when it was compiled. It will tell you the version of the ogg vorbis libraries that were used in the compilation, various other pieces of information and my email address, which is at the top of this guide, anyway!
I hope that this guide has been of some use to you. If you have any suggestions as to how this may be improved, or you have found any errors, please feel free to mail me. Any suggestions received will be given the proper consideration.