Content-type: text/html Manpage of xmpgedit

xmpgedit

Section: User Commands (1)
Index Return to Main Contents

NAME

xmpgedit - MPEG 1/2/2.5 audio (mp3) file editor

SYNOPSIS

xmpgedit [inputfile1 [inputfile2...]]

xmpgedit [-c] [-h] [-O offsec.offmsec] [-e [start[-[end]]]] [-f inputfile]

DESCRIPTION

xmpgedit is the graphical user interface (GUI) implementation of mpgedit. xmpgedit supports most of the same editing features of mpgedit. xmpgedit uses the GTK+ 2.0 toolkit, on both Linux and Windows. The windows installer distribution also installs GTK+ for Windows as part of the install process.

xmpgedit is an MPEG 1 layer 1/2/3, MPEG 2, and MPEG 2.5 audio (mp3) file editor that is capable of processing both Constant Bit Rate (CBR) and Variable Bit Rate (VBR) encoded files. xmpgedit can cut an input MPEG file into one or more output files, as well as join one or more input MPEG files into a single output file. When editing VBR files that have a XING header, xmpgedit updates the output file's XING header information to reflect the new file size and average bit rate.

When editing a file, xmpgedit locates the nearest MPEG frame boundary for the desired start and end times, then copies the frames between these times to the output file. Since no file decoding / encoding occurs during editing, there is no audio quality loss when editing with xmpgedit. For each file being edited, a time index file is created that stores the file position, in bytes, for every 1 second of play time. Indexing guarantees correct and fast random access to edit time offsets for VBR-encoded files.

xmpgedit file playback allows edit-time audio playback auditioning, which insures that desired cut occurs at the correct time offset. This feature is necessary when making edits that demand sub-second accuracy (especially with VBR files). Since most MP3 players display playback run times based on a VBR file's average encoded bit rate, edits based on these players' displayed times can miss the desired start or stop time by many seconds.

xmpgedit resembles an MP3 audio player when started. A toolbar is present at the top of the interface. Below the toolbar is the file edit list. Below the edit window is a playback status area. Below the status area are found two nearly identical audio playback controls.

These playback controls are used to specify edit start and stop times for the currently selected file. The top playback control is used to specify the edit start time, the bottom specify the edit end time. The play button works as expected; playback occurs when clicked in, and stopped when clicked out. The record button can be pressed at any time, either during playback, or after an edit time selection has been changed. By doing so, the time during playback when the record button is pressed, or the specified edit time is recorded in the edit list. The play previous button plays back from 5 seconds before the currently selected edit time, stopping after 5 seconds of material has been played. The default playback control buttons are the play button, the record button, and the play previous button. The pause button, stop button and volume control can be enabled through the File->Options menu.

Edit times are specified using either the scroll bar below the play buttons, or the time spinner buttons to the right of the play buttons. An edit time can also be typed directly into the numeric fields immediately to the left of each spinner button set. These three fields set the edit minute, second and millisecond values respectively.

When using audio playback to test an edit time, that edit time can be adjusted using either the spinner buttons, or the scroll bar. When the time is changed, playback immediately stops. Playback will now start from the newly specified edit time. Using this combination of playback, and edit time modification, searching for the desired edit point is quickly accomplished. Once the desired edit point is found, pressing the record button stores the edit time in the edit list for the highlighted entry. Both a start and end edit time must be selected for each file loaded into the editor.

The tool bar File and Edit menus are also available as popup menus. When the mouse cursor is over a blank area in the playback control area, clicking the right mouse button (a right click) will popup the File menu. A right click anywhere in the edit list area will popup the Edit menu.

COMMAND LINE OPTIONS

xmpgedit has the following command line options:

-c: Curses edit mode. This option is accepted but ignored. This is present for compatibility with scripts written for mpgedit and xmpgedit.
-e: -e start[-[end]] Perform copy/paste operation on input files. The input MP3 file may be encoded as either CBR or VBR. For quick and accurate random access to VBR-encoded files, an external time index file is created. The index file uses the basename of the input file with the '.idx' extension.
-f input file name: Use the named input file. Multiple -f options are allowed. At least one -e option must be precede each -f option.
-h: Print xmpgedit usage.
-O offset_sec.offset_msec
-O offset_sec:offset_msec: Sepecify offset time for zero second start for input MP3 file. This option specifies a new zero second start time for the input MP3 file. This option is useful when editing an MP3 file that has recorded lead-in material using a known playlist of start/stop times. In this situation, the lead-in material must be ignored for the first recorded selection's start time to match the playlist. The start time is specified in seconds and milliseconds, separated by . or a :.

FILE MENU CONTROLS

Each of the controls present on the File menu are described in detail in this section. Presenting the operating details of these controls will reveal some of the features of xmpgedit.

Open File...: Open an input file selection control. Navigate to the directory containing audio files to edit, then select a file ending with the .mp3, .mp2 or .mp1 extension. Additionally, selecting files named with the .idx extension are assumed to be .mp3 files. For example, selecting test1.idx is the same as selecting test1.mp3. The arrow up control on the far right of the playback status area also opens the file selection control. The name of a file to edit can be entered on the edit line directly left of the arrow up control. Once a file to edit is selected, a new entry for that file is appended to the end of the edit list.
Output File...: Output file name control. Specify the output file name on the text edit line at the top of this control. Pressing the Open button opens a file selection control to browse to the directory that contains the desired output file. This feature is useful when joining edits (appending) with an existing file. xmpgedit operates in two editing modes: Join and Split. The Join mode appends all specified edits into a single output file. The Split mode saves each edit into a separate output file, uniquely named with a numeric suffix. For example, when the output file name test1 is specified and Split is selected, edits are saved into output files named test1_1.mp3, test1_2.mp3, test1_3.mp3, and so on. Note that this numbering always begins with 1, which means if the file test1_1.mp3 already exits, the edit will fail. The default edit mode is Split and the default output file name is the name of the first input file loaded into the editor, with an underscore appended to the name. For example, when test1.mp3 is the first file loaded into the editor, the default output file name is test1_.
Save Session...: Save Session file selection control. All of the files and edit times that appear in the edit list window are saved to the file named in this control. Specify the name of the file to save the edit session on the text edit line at the top of this control. Press the Open button to open a file selection control to browse to the directory and select the name of an existing file to save the edit session. The default save session file name is .mp3edit_abandoned. When the file .mp3edit_abandoned_name exists, the name stored in this file is used. This means the last file name entered in the Save Session... dialog will become the default save session file name.
Load Session...: Load Session file selection control. Edits previously saved using Save Session... are loaded into the editor. The edit session is also saved during the file editing process, by selecting File->Edit. Specify the name of the save session to load on the text edit line at the top of this control. Press the Open button to open a file selection control and browse to the directory containing the saved session file. Files named with a leading . do not appear in this file selection control by default. Enter .<TAB> (a period followed by the TAB key) on the text edit line and all files beginning with a . will appear. This mechanism is a generic way of narrowing the files listed in the file selection control. Specifying test1<TAB> will cause the selection control to list only files beginning with test.
Edit: Edit files. All edits specified in the edit list window are performed. Edits are saved to default output filename, unless specified by File->Output file... option. The default output filename is the same basename as the input file, with the '_nn.mp3' extension appended. Refer to the Output file... section for more details. The current edit list is saved to the save session file before performing the specified edits. The save session output file is specified with File->Save Session.... When the save session file already exists, a warning dialog is displayed, and a new name can be specified, or the existing file can be overwritten.
Set Offset: Sepecify offset time for zero second start for input MP3 file. This feature specifies a new zero second start time for the input MP3 file. This option is useful when editing an MP3 file that has recorded lead-in material using a known playlist of start/stop times. In this situation, the lead-in material must be ignored for the first recorded selection's start time to match the playlist. The currently selected Playback time is set as the new offset time after the Set Offset action is taken. When viewing the volume levels with the Decode feature (see below), you must click on the file name in the edit list for the specified offset time to take effect.

: Note: The Options->Offset time check box must be selected before the Set Offset menu entry is visible.

Decode

Display decoded MP3 file volume levels. This option decodes the selected file in the editor, then opens a graphical viewer/editor to display the file's volume levels. Because this operation is computationally expensive, this option is not the default. To help improve performance, only every third frame in the input file is decoded. The decoded results are stored in the file named prefix.lvl, where prefix is the basename component of the input file selected. Once loaded into the viewer, edit times can be selected by left-clicking the mouse on the desired time on the volume level display. A single click selects the Playback time, which can then be saved as a start or stop edit time by clicking on the green Record start time or red Record end time buttons. Left clicking and holding then dragging the cursor to the right or left across the volume levels will highlight all of the segment that will be included in the edit. Releasing the mouse button then sets the start and end edit times. Dragging the cursor out of the volume viewer to the right or left while holding the mouse button will cause the display to scroll to show additional volume levels.

Statistics

Display MP3 file statistics. This option displays file size and frame statistics about the selected file in the editor. Information displayed in this display includes the file's name, VBR maximum/minimum/average encoding bitrate, total frames, file size, playback length and a detailed breakdown of frame bitrates for VBR encoded files.

Options...

Configurable options. xmpgedit configurable options are set using this menu. These options are selected by this menu:

: * The playback pause button

: * The playback stop button

: * The volume control

: * The start Offset time LED display.

: Note: Enabling this option also adds the Set Offset control to the File menu list.

: The configuration is saved to the file .xmpgeditrc in the current working directory.

Exit

Quit xmpgedit. When changes to the current edit list have not been committed to a save session file, a warning dialog is displayed. xmpgedit is not quit when cancel is clicked. Afterwards, select File->Save Session... to commit the edit list to a save session file.

EDIT MENU CONTROLS

Cut: Copy the selected row in the edit list to the save buffer, and delete. The cut row can be pasted using the Edit->Append option.
Copy: Copy the selected row in the edit list to the save buffer. The copied row can be pasted using the Edit->Append option.
Append: Append the edit line from the save buffer into the row below the currently selected row. The saved row can be pasted as the very first row in the editor by selecting the blank row at the top of the edit list before using the Edit->Append option.
Copy/Chain: Copy the selected row in the edit list and paste it below the current row. The start and end times of the new row are the same as the end time of the previous row. Since the start time of the new row starts with the end time of the previous row, this operation links or chains the two edit lines together.
Copy/Append: Duplicate selected row. This option is similar to performing an Edit->Copy followed by an Edit->Append, but the appended line is always the next line following the line copied with this action. Additionally, the save buffer is not used with Copy/Append.
Copy Start Time: Initialize the end time of the selected row using the start time of the next row. In other words, this action chains the end time of the current edit with the start time of the next edit.
Copy End Time: Initialize the start time of the the selected row using the end time of the previous row. This option is useful when editing a single file that contains a series of tracks that will be split into individual files. Typically, the start time of each segment begins at the end time of the previous segment. Even when the current start time does not begin with exactly the same previous end time, using the Copy End Time option initializes the start time to a value that is close to the desired edit time.
Clear Editor: This action deletes all edits from the edit list and resets xmpgedit. Caution: Any unsaved edits are destroyed by this action.

HELP MENU CONTROLS

About: Display xmpgedit copyright and credits dialog.

EXAMPLES

This example demonstrate how to cut a single file into 4 pieces, then merge those 4 files into a single output file.

Edit a file into 4 pieces.

Start xmpgedit.

Enter the input file name test1.mp3. This can be accomplished by typing the path into the File: name edit line, or by using File->Open File..., or clicking the up arrow. Repeat until there are 4 entries in the edit window for test1.mp3. As a short cut, after the first file is loaded, just press <ENTER> in the file name edit line until 4 entries appear in the editor.

Click on the first line in the edit window.

Specify an end edit time of 6 seconds using the End Time: playback spinner or scroll bar controls. Click the record button.

Click on the second line in the edit window.

Right click in the edit window, and select Copy End Time. The start time is now set to the end time of the first line.

Again use the End Time: edit time controls to now specify an end time of 12 seconds. Now click on the third line in the edit window without first pressing the record buttons. A dialog asking to record the unsaved changes appears. Click OK.

Use Copy End Time to initialize the start edit time. Set the end edit time to 18 seconds. Press the play previous button. The previous 5 seconds of material before the specified edit time is played.

Click the fourth line in the editor. Once again, use Copy End Time to specify the start edit time. Move the end edit time slider to the far right.

Right click in a blank area in the playback controls area, and select Edit. Click OK to commit any unsaved changes. Edit progress bars display as the edits proceed. Because these edits are so short, the progress bars are only displayed briefly.

In the edit list area, right click and select Clear Editor. The editor is now initialized to an empty state.

Joining 4 files into a single file.

Select from the main tool bar File->Load Session..., and accept the default session .mp3edit_abandoned. The edit session previously performed is now loaded into the editor.

Select from the main tool bar File->Output File.... Remember that right clicking over a blank area in the playback controls area also brings up the main menu. In the Output file name dialog, select the Join radio button, and enter the output file name test_join, then click OK.

Right click over the playback area, and select Edit. The four files listed in the editor have now been joined together into a single file, named test1_join.mp3. This file is identical to the original test1.mp3 input file.

Example selecting edit times by playback

This example demonstrates how to locate edit times by listening to the file being edited. This technique is useful when editing a file where the edit start and stop times are not known in advance, such as music recorded from satellite radio.

Start xmpgedit

Load test1.mp3 into the editor.

Push the End Time play button. While the file is playing, push the record button. Notice the end time in the edit list is updated each time the record button is pressed. There is a brief period of silence between 6 and 7 seconds. Practice finding that time using the record button. Test the selected time by playing back the selected edit time using the Play Previous and Play buttons. Use the second and millisecond spinner buttons to refine the candidate end time. The first edit end time should be 6.5 seconds.

Over the edit list Right click and select Copy/Append. Then Right click and select Copy End Time. Using the technique described above, locate the edit end time. The second edit end time is 12.5 seconds.

Again, Right click->Copy/Append and Right click->Copy End Time to create the third edit entry. Locate the third edit end time using the above technique. The third edit end time is at 19 seconds. Verify this is correct by using the Play and Play Previous controls.

Once again, Right click->Copy/Append and Right click->Copy End Time to create the fourth and final edit entry. This time slide the end time scroll bar to the far right, and press the Record button.

Select File->Output file... and specify second_test as the output file name, and press <ENTER>.

Select File->Edit to perform the specified edits.

GTK CONFIGURATION

xmpgedit pixmap images are located in /usr/local/share/xmpgedit, or /basedir/share/xmpgedit when installed in a directory other than the default. This information must be configured in one of these two locations:

: - $HOME/.xmpgedit-gtkrc
- /usr/local/etc/gtk-2.0/gtkrc

Add the following entry to these files:

: pixmap_path "/usr/local/share/xmpgedit"

The UNIX mpgedit install script attempts to update the global gtkrc file. However, this will not occur when the location of this file cannot be determined. In this case, the appropriate pixmap_path entry must be added manually.

Note: It is not necessary to add this entry to the $HOME/.xmpgedit-gtkrc file when added to the global gtkrc file.

PLAYBACK CONFIGURATION

xmpgedit requires configuration for the sound playback feature to work. As root, run make install. For Linux as part of the installation, the shared library loader is configured to search the directory where xmpgedit was installed. These are the actions performed by the install process to configure the shared library loader:

: echo /usr/local/lib >> /etc/ld.so.conf
/sbin/ldconfig

Sound playback is implemented using two mechanisms: 1) an external command line MP3 player capable of standard input file playback, and 2) the MPGLIB decoder library that ships with the LAME project. The default playback configuration uses the MPGLIB-based decoder plugin libdecoder_mpg123.so.

Two decoder plugin implementations ship with xmpgedit: libdecoder_popen.so and libdecoder_mpg123.so. libdecoder_popen.so will execute the mp3decoder.sh script for file playback. libdecoder_mpg123.so is implemented using the MPGLIB decoder library present in LAME. This implementation also serves as a sample implementation of a single process playback plugin that could be ported to the Microsoft Windows(R) operating systems, and other operating systems that do not support the popen() system call.

xmpgedit attempts to load the playback plugin libmpgedit_decoder.so when file playback is specified. When the decoder plugin is loaded, it is used for file playback. When the decoder plugin cannot be loaded, the default action is to execute the mp3decoder.sh script.

libmpgedit_decoder.so is installed as a symbolic link pointing to one of the playback plugins, libdecoder_mpg123.so or libdecoder_popen.so. make install installs the libdecoder_mpg123.so playback plugin. libdecoder_popen.so can be installed manually when use of a command line MP3 player is desired.

To use a different command line MP3 player, configure libdecoder_popen.so as the playback plugin, then edit the mp3decoder.sh file to call the desired MP3 player. This shell script is then loaded by xmpgedit when performing file playback, and provides the flexibility to specify any MP3 player that can play files from standard input.

IMPLEMENTATION LIMITATIONS AND ANOMALIES

- Decoding of some MP3 files does not give good visualization results. This is

because of limitations with the current skip frame decoding implementation. A work-around has been found which improves visualization results. Use this command to decode files which give poor visualization results:

mpgedit -D -d 1 input.mp3

Note: You must first delete input.lvl before running this command.

- Since release 0.6p1, mpgedit has been tested with MPEG 1 layer 1/2/3,

MPEG 2 layer 1/2/3 and MPEG 2.5 layer 3 files. Since MPEG 2.5 layer 1/2 files have the same frame header structure, it is assumed this program will function properly with such files, although no testing on files encoded with this format has occurred. These same issues apply to xmpgedit.

- While it is possible with xmpgedit to join together files that

consist of differing encoding versions (MPEG-1 and MPEG-2, for example) and sample rates (44.1KHz and 22.05KHz, for example), caution must be used. Although such a file is technically a legal encoding, it is doubtful that all (or any, for that matter) MP3 players will be able to correctly render such a file.

- Any ID3 tags present in input files are not present in the output from

an edit. Output files must be tagged to restore ID3 information.

- xmpgedit implements an MPEG audio frame header parser that is tolerant of

many encoder errors, corrupted data, and files with formats that are not strictly MPEG audio files. When such an encoding error is encountered, all data between the last correctly encoded frame and the next recognized frame are silently skipped. Other programs, such as mp3_check, perform a more detailed validity check and report where errors occur, and are likely to be more robust when handling corrupted data files.

- Using the libdecoder_mpg123.so

plugin, mpgedit properly plays all of the ISO MPEG conformance files, as well as MPEG 2/2.5 files encoded using lame. Two exceptions can be noted. Win32 does not properly handle MPEG 2/2.5 files encoded at with a sample rate of 11025Hz/mono. A work around in the libdecoder_mpg123.so decoder plugin is implemented, but the sound quality suffers. The MPEG 1 layer 1 mono test file http://mpgedit.org/mpgedit/testdata/mpeg1/layer1/fl4.mp1 does not render properly. All the data used to exercise mpgedit is located at http://mpgedit.org/mpgedit/testdata/mpegdata.html.

- During development, the previous name of the program was mp3edit.

The final name mpgedit was settled on after much development occurred. Because of this, many source files and function names are called mp3_. You will also see mpeg_ instead of mpg_ in some cases.

ACKNOWLEDGEMENTS AND HISTORY

The first prototype implementation of MP3 file editing was based upon the mp3_check program, written by Eric Bullen, http://sourceforge.net/projects/mp3check. Because the project goals of mp3_check are different than mpgedit, the idea of integrating editing functionality into mp3_check was abandoned. Many of the current command line options for mpgedit can be traced to the early prototype work done with mp3_check.

mpgedit is a completely independent implementation from the early mp3_check editing prototype. While some of the early ideas from this prototype still exist in mpgedit, everything has been re-implemented.

Finding reference material sufficiently complete to implement mpgedit was difficult. The O'Reilly & Associates book "MP3: The Definitive Guide" by Scot Hacker http://www.oreilly.com/catalog/mp3/, while accurate in its description of the MPEG audio file frame header structure, did not contain sufficient detail to fully implement the MPEG file parsing functionality. The document that proved invaluable for completing the MPEG audio frame header parsing code was written by Predrag Supurovic, http://www.dv.co.yu/mpgscript/mpeghdr.htm.

The MPGLIB decoding engine comes from the MPG123 package, written by Michael Hipp (www.mpg123.de). MPGLIB is released under the GPL. The version of MPGLIB used for building the libdecoder_mpg123.so decoder plugin comes from the 3.90 alpha 7 version of LAME http://sourceforge.net/projects/lame. Earlier versions of LAME do not include a shared library build of MPGLIB, which is needed when building the decoder plugin. The MPGLIB that comes with mpg123-0.59r can also be used when linking the libdecoder_mpg123.so plugin. However, LAME appears to have fixed some bugs that mpg123 has not.

Special thanks go to Jared Benedict <http://redjar.org/jared/> and Public Radio Exchange <http://www.prx.org/> for the donation of a Macintosh G3 B&W computer. Completion of the port to Mac OSX 10.3 was possible using this system.

The initial port of the command line and curses mpgedit to Mac OSX 10.1 was done with thanks to Tony Andrea <tony.andrea@pobox.com>.

Thanks to Colin Bell <cpb@tklogic.net> for helping with freshing the Mac OSX 10.1 port.

Index

NAME
SYNOPSIS
DESCRIPTION
COMMAND LINE OPTIONS
FILE MENU CONTROLS
EDIT MENU CONTROLS
HELP MENU CONTROLS
EXAMPLES
GTK CONFIGURATION
PLAYBACK CONFIGURATION
IMPLEMENTATION LIMITATIONS AND ANOMALIES
ACKNOWLEDGEMENTS AND HISTORY
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 21:47:16 GMT, January 25, 2009