‘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.

Plugins¶

Plugins

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:

# eyeD3 config file.
# default: ~/.eyeD3/config.ini
# overridde using -c/--config 
[default]

# Default plugin to use.
plugin = 

# General options to always use. These can be plugin specific but SHOULD NOT be.
# Any -C/--config and -P/--plugin options are ignored.
options =
#options = --pdb

# Extra directories to load plugins. Separated by ':'
plugin_path = ~/.eyeD3


# vim: set filetype=dosini:

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 Configuration Files) that inherits from 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.

import eyed3
from eyed3.plugins import Plugin
from eyed3.utils import guessMimetype


class EchoPlugin(eyed3.plugins.Plugin):
    NAMES = ["echo"]
    SUMMARY = u"Displays each filename and mime-type passed to the plugin"

    def handleFile(self, f):
        print("%s\t[ %s ]" % (f, guessMimetype(f)))

Many plugins might prefer to deal with only file types eyeD3 natively supports, namely mp3 audio files. To automatically load eyed3.core.AudioFile objects using eyed3.core.load() inherit from the 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.

from eyed3.plugins import LoaderPlugin


class Echo2Plugin(LoaderPlugin):
    SUMMARY = u"Displays details about audio files"
    NAMES = ["echo2"]

    def handleFile(self, f):
        super(Echo2Plugin, self).handleFile(f)

        if not self.audio_file:
            print("%s: Unsupported type" % f)
        else:
            print("Audio info: %s Metadata tag: %s " %
                  ("yes" if self.audio_file.info else "no",
                   "yes" if self.audio_file.tag else "no"))

Documenting Plugins¶

Plugin docs are generated. Start each plugin with the following template; but replace the square brackets with curly.*

Example Plugin
===============

.. [[[cog
.. cog.out(cog_pluginHelp("example-plugin"))
.. ]]]

.. [[[end]]]

The documentation build process will run eyeD3 –plugin example-plugin and generate docs from the command line options and plugin metadata such as the description. The plugin index in cli.rst should also me updated to include the new plugin.