Fetching contributors…
Cannot retrieve contributors at this time
110 lines (84 sloc) 4.11 KB

'eyeD3' Command Line Tool

The eyeD3 command line interface is based on plugins. The main driver knows how to traverse file systems and load audio files for hand-off to the plugin to do something interesting. With no plugin selected a simplified usage is:

$ eyeD3 --help
usage: eyeD3 [-h] [--version] [--exclude PATTERN]
             [--plugins] [--plugin NAME]
             [PATH [PATH ...]]

positional arguments:
  PATH                  Files or directory paths

optional arguments:
  -h, --help            show this help message and exit
  --version             Display version information and exit
  --exclude PATTERN     A regular expression for path exclusion. May be
                        specified multiple times.
  --plugins             List all available plugins
  --plugin NAME         Specify which plugin to use.

The PATH argument(s) along with optional usage of --exclude are used to tell eyeD3 what files or directories to process. Directories are searched recursively and every file encountered is passed to the plugin until no more files are found.

To list the available plugins use the --plugins option and to select a plugin pass its name using --plugin=<name>.

If no --plugin= option is provided the default plugin is selected. Currently this is set to be the command line tag viewer/editor that has been the primary interface in all versions of eyeD3 prior to 0.7.x.


.. toctree::
   :maxdepth: 1


Configuration Files

Command line options can be read from a configuration file using the -C/--config option. It expects a path to an Ini file contain sections with option values. A sample config file, for example:

.. literalinclude:: ../examples/config.ini
   :language: ini

If the file ${HOME}/.eyeD3/config.ini exists it is loaded each time eyeD3 is run and the values take effect. This can be disabled with --no-config.

Custom Plugins

Plugins are any class found in the plugin search path (see 'plugin_path' in :ref:`config-files`) that inherits from :class:`eyed3.plugins.Plugin`. The interface is simple, the basic attributes of the plugin (name, description, etc.) are set using menber variables and for each file eyeD3 traverses (using the given path(s) and optional --exclude options) the method handleFile will be called. The return value of this call is ignored, but if you wish to halt processing of files a StopIteration exception can be raised. Here is where the plugin should does whatever interesting it things it would like to do with the files it is passed. When all input files are processed the method handleDone is called and the program exits. Below is an 'echo' plugin that prints each filename/path and the file's mime-type.

.. literalinclude:: ../examples/plugins/

Many plugins might prefer to deal with only file types eyeD3 natively supports, namely mp3 audio files. To automatically load :class:`eyed3.core.AudioFile` objects using :func:`eyed3.core.load` inherit from the :class:`eyed3.plugins.LoaderPlugin` class. In this model the member self.audio_file is initialized to the parsed mp3/id3 objects. If the file is not a supported audio file type the value is set to None.

In the next example the LoaderPlugin is used to set the audio_file member variable which contains the info and tag objects.

.. literalinclude:: ../examples/plugins/

.. seealso:: :ref:`config-files`,
             :class:`eyed3.mp3.Mp3AudioInfo`, :class:`eyed3.id3.tag.Tag`