‘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¶
- classic - Tag Viewer/Editor
- display - Display tag information by pattern
- fixup - Music directory fixer
- itunes-podcast - Convert files so iTunes recognizes them as podcasts
- genres - ID3 Genre List
- lameinfo (xing) - Lame (Xing) Header Information
- nfo - (I)NFO File Generator
- pymod - Use simple python modules as eyeD3 plugins
- stats - Music Collection Statistics
- xep-118 - Jabber (XMPP) Tune Format
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.
from __future__ import print_function
import eyed3
from eyed3.plugins import Plugin
from eyed3.utils import guessMimetype
eyed3.require((0, 7))
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.
# -*- coding: utf-8 -*-
from __future__ import print_function
import eyed3
from eyed3.plugins import LoaderPlugin
eyed3.require((0, 7))
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"))