Commits

Travis Shirk committed f80cf3d

Docs

Comments (0)

Files changed (5)

 To list the available plugins use the ``--plugins`` option and to select a
 plugin pass its name using ``--plugin=<name>``.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "PLUGINS_LIST", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "PLUGINS_LIST",
+                      lang="bash") }}}
 .. {{{end}}}
 
 If no ``--plugin=`` option is provided the *default* plugin is selected.
    plugins/stats_plugin
    plugins/xep118_plugin
 
+.. _config-files:
+
 Configuration Files
 -------------------
 
 `Ini <http://docs.python.org/2/library/configparser.html>`_ file contain
 sections with option values. A sample config file, for example:
 
-.. literalinclude:: ../etc/config.ini
+.. literalinclude:: ../examples/config.ini
    :language: ini
 
 If the file ``${HOME}/.eyeD3/config.ini`` exists it is loaded each time eyeD3
 
 Custom Plugins
 --------------
-TODO
+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/echo.py
+
+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/echo2.py
+
+
+.. seealso:: :ref:`config-files`,
+             :class:`eyed3.plugins.Plugin`,
+             :class:`eyed3.plugins.classic.ClassicPlugin`,
+             :class:`eyed3.mp3.Mp3AudioInfo`, :class:`eyed3.id3.tag.Tag`
+

docs/plugins/classic_plugin.rst

 eyeD3 can do more than edit exiting tags, it can also create new tags from
 nothing. For these examples we'll make a dummy file to work with.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "SETUP", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "SETUP", lang="bash") }}}
 .. {{{end}}}
 
 Now let's set some common attributes like artist and title.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "ART_TIT_SET", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "ART_TIT_SET",
+                      lang="bash") }}}
 .. {{{end}}}
 
 Most options have a shorter name that can be used to save typing. Let's add
 the album name (``-A``), the genre (``-G``), and the year (``-Y``) the
 record was released.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "ALB_YR_G_SET", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "ALB_YR_G_SET",
+                      lang="bash") }}}
 .. {{{end}}}
 
 Notice how the genre displayed as "Hardcore (id 129)" in the above tag listing.
 store any value you'd like. For a list of recognized genres and their
 respective IDs see the `genres plugin <genres_plugin.html>`_.
 
-TODO: reference genres plubin
-
-.. {{{cog cli_example("bin/cli_examples.sh", "NONSTD_GENRE_SET", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "NONSTD_GENRE_SET",
+                      lang="bash") }}}
 .. {{{end}}}
 
 By default writes ID3 v2.4 tags. This is the latest standard and supports
 data field is not supported, but eyeD3 does its best to convert when the
 data whenever possible.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "CONVERT1", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "CONVERT1", lang="bash") }}}
 .. {{{end}}}
 
 The last conversion above converted to v1.1, or so the output says. The 
 the non-standard genre was lost by the conversion, thankfully it is still
 in the v2 tag.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "DISPLAY_V1", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "DISPLAY_V1", lang="bash") }}}
 .. {{{end}}}
 
 The ``-1`` and ``-2`` options also determine which tag will be edited, or even
 which tag will be converted when one of the conversion options is passed.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "SET_WITH_VERSIONS", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "SET_WITH_VERSIONS", lang="bash") }}}
 .. {{{end}}}
 
 At this point the tag is all messed up with by these experiments, you can always
 remove the tags to start again.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "REMOVE_ALL_TAGS", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "REMOVE_ALL_TAGS", lang="bash") }}}
 .. {{{end}}}
 
 Complex Options
   eyeD3: error: argument --add-image: invalid ImageArg value: 'http://example.com/cover.jpg:FRONT_COVER'
 
 The problem is the ':' character in the the URL, it confuses the format description of the option value. To solve this escape all delimeter characters in 
-option values with '\'. 
+option values with '\\'. 
 
-.. {{{cog cli_example("bin/cli_examples.sh", "IMG_URL", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "IMG_URL", lang="bash") }}}
 .. {{{end}}}
 

docs/plugins/genres_plugin.rst

 Example
 -------
 
-.. {{{cog cli_example("bin/cli_examples.sh", "GENRES_PLUGIN1", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "GENRES_PLUGIN1", lang="bash") }}}
 .. {{{end}}}

docs/plugins/lameinfo_plugin.rst

 Example
 -------
 
-.. {{{cog cli_example("bin/cli_examples.sh", "LAME_PLUGIN", lang="bash") }}}
+.. {{{cog cli_example("examples/cli_examples.sh", "LAME_PLUGIN", lang="bash") }}}
 .. {{{end}}}

examples/echo2.py

         if not self.audio_file:
             print("%s: Unsupported type" % f)
         else:
-            print(self.audio_file)
+            print("Audio info: %s Metadata tag: %s " %
+                  ("yes" if self.audio_file.info else "no",
+                   "yes" if self.audio_file.tag else "no"))
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.