mirror of
https://github.com/beetbox/beets.git
synced 2025-12-30 04:22:40 +01:00
docs: reorg plugins section; add dev section
--HG-- rename : docs/plugins/writing.rst => docs/dev/plugins.rst
This commit is contained in:
Adrian Sampson
parent
60f592ec9f
commit
e6725b6973
7 changed files with 48 additions and 54 deletions
4
docs/dev/api.rst
Normal file
4
docs/dev/api.rst
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
API Documentation
|
||||
=================
|
||||
|
||||
TK.
|
||||
10
docs/dev/index.rst
Normal file
10
docs/dev/index.rst
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
For Developers
|
||||
==============
|
||||
|
||||
This section contains information for developers. Read on if you're interested
|
||||
in hacking beets itself or creating plugins for it.
|
||||
|
||||
.. toctree::
|
||||
|
||||
plugins
|
||||
api
|
||||
|
|
@ -20,7 +20,7 @@ comes from MusicBrainz. Plugins can provide :doc:`album art
|
|||
|
||||
If you want beets to get any of this data automatically during the import
|
||||
process, just enable any of the three relevant plugins (see
|
||||
:ref:`using-plugins`). For example, put this line in your :doc:`config file
|
||||
:doc:`/plugins/index`). For example, put this line in your :doc:`config file
|
||||
</reference/config>` to enable all three::
|
||||
|
||||
plugins: fetchart lyrics lastgenre
|
||||
|
|
@ -67,7 +67,7 @@ but play it at work (without copying my whole library locally). The
|
|||
:doc:`/plugins/web` makes streaming your music easy---it's sort of like having
|
||||
your own personal Spotify.
|
||||
|
||||
First, enable the ``web`` plugin (see :ref:`using-plugins`). Run the server by
|
||||
First, enable the ``web`` plugin (see :doc:`/plugins/index`). Run the server by
|
||||
typing ``beet web`` and head to http://localhost:8337 in a browser. You can
|
||||
browse your collection with queries and, if your browser supports it, play
|
||||
music using HTML5 audio.
|
||||
|
|
|
|||
|
|
@ -238,7 +238,7 @@ is possible. You'll also want to glance over the :doc:`/reference/cli` page
|
|||
for a more detailed description of all of beets' functionality. (Like
|
||||
deleting music! That's important.)
|
||||
|
||||
Also, check out :ref:`included-plugins` as well as :ref:`other-plugins`. The
|
||||
Also, check out :doc:`beets' plugins </plugins/index>`. The
|
||||
real power of beets is in its extensibility---with plugins, beets can do almost
|
||||
anything for your music collection.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ to build your music library.
|
|||
|
||||
Then you can get a more detailed look at beets' features in the
|
||||
:doc:`/reference/cli/` and :doc:`/reference/config` references. You might also
|
||||
be interested in exploring the :ref:`included-plugins`.
|
||||
be interested in exploring the :doc:`plugins </plugins/index>`.
|
||||
|
||||
If you still need help, your can drop by the ``#beets`` IRC channel on Freenode,
|
||||
`email the author`_, or `file a bug`_ in the issue tracker. Please let me know
|
||||
|
|
@ -30,6 +30,7 @@ Contents
|
|||
reference/index
|
||||
plugins/index
|
||||
faq
|
||||
dev/index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
|
|||
|
|
@ -1,40 +1,20 @@
|
|||
Plugins
|
||||
=======
|
||||
|
||||
Plugins can extend beets' core functionality. Plugins can add new commands to
|
||||
the command-line interface, respond to events in beets, augment the autotagger,
|
||||
or provide new path template functions.
|
||||
Plugins extend beets' core functionality. They add new commands, fetch
|
||||
additional data during import, provide new metadata sources, and much more. If
|
||||
beets by itself doesn't do what you want it to, you may just need to enable a
|
||||
plugin---or, if you want to do something new, :doc:`writing a plugin
|
||||
</dev/plugins>` is easy if you know a little Python.
|
||||
|
||||
.. _using-plugins:
|
||||
|
||||
Using Plugins
|
||||
-------------
|
||||
|
||||
To use a plugin, you have two options:
|
||||
|
||||
* Make sure it's in the Python path (known as `sys.path` to developers). This
|
||||
just means the plugin has to be installed on your system (e.g., with a
|
||||
`setup.py` script or a command like `pip` or `easy_install`).
|
||||
|
||||
* Set the `pluginpath` config variable to point to the directory containing the
|
||||
plugin. (See :doc:`/reference/config`.)
|
||||
|
||||
Then, set the `plugins` option in your `config.yaml` file, like so::
|
||||
To use one of the plugins included with beets (see below for a list), just use
|
||||
the `plugins` option in your `config.yaml` file, like so::
|
||||
|
||||
plugins: mygreatplugin someotherplugin
|
||||
|
||||
The value for `plugins` can be a space-separated list of plugin names or
|
||||
a YAML list like ``[foo, bar]``.
|
||||
|
||||
You can see which plugins are currently enabled by typing ``beet version``.
|
||||
|
||||
.. _included-plugins:
|
||||
|
||||
Plugins Included With Beets
|
||||
---------------------------
|
||||
|
||||
There are a few plugins that are included with the beets distribution. They're
|
||||
disabled by default, but you can turn them on as described above.
|
||||
The value for `plugins` can be a space-separated list of plugin names or a
|
||||
YAML list like ``[foo, bar]``. You can see which plugins are currently enabled
|
||||
by typing ``beet version``.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
|
@ -71,7 +51,7 @@ disabled by default, but you can turn them on as described above.
|
|||
ftintitle
|
||||
|
||||
Autotagger Extensions
|
||||
''''''''''''''''''''''
|
||||
---------------------
|
||||
|
||||
* :doc:`chroma`: Use acoustic fingerprinting to identify audio files with
|
||||
missing or incorrect metadata.
|
||||
|
|
@ -84,7 +64,7 @@ Autotagger Extensions
|
|||
.. _Discogs: http://www.discogs.com/
|
||||
|
||||
Metadata
|
||||
''''''''
|
||||
--------
|
||||
|
||||
* :doc:`lyrics`: Automatically fetch song lyrics.
|
||||
* :doc:`echonest_tempo`: Automatically fetch song tempos (bpm).
|
||||
|
|
@ -99,7 +79,7 @@ Metadata
|
|||
field.
|
||||
|
||||
Path Formats
|
||||
''''''''''''
|
||||
------------
|
||||
|
||||
* :doc:`inline`: Use Python snippets to customize path format strings.
|
||||
* :doc:`rewrite`: Substitute values in path formats.
|
||||
|
|
@ -107,7 +87,7 @@ Path Formats
|
|||
end).
|
||||
|
||||
Interoperability
|
||||
''''''''''''''''
|
||||
----------------
|
||||
|
||||
* :doc:`mpdupdate`: Automatically notifies `MPD`_ whenever the beets library
|
||||
changes.
|
||||
|
|
@ -115,7 +95,7 @@ Interoperability
|
|||
* :doc:`smartplaylist`: Generate smart playlists based on beets queries.
|
||||
|
||||
Miscellaneous
|
||||
'''''''''''''
|
||||
-------------
|
||||
|
||||
* :doc:`web`: An experimental Web-based GUI for beets.
|
||||
* :doc:`random`: Randomly choose albums and tracks from your library.
|
||||
|
|
@ -138,6 +118,20 @@ Miscellaneous
|
|||
Other Plugins
|
||||
-------------
|
||||
|
||||
In addition to the plugins that come with beets, there are several plugins
|
||||
that are maintained by the beets community. To use an external plugin, there
|
||||
are two options for installation:
|
||||
|
||||
* Make sure it's in the Python path (known as `sys.path` to developers). This
|
||||
just means the plugin has to be installed on your system (e.g., with a
|
||||
`setup.py` script or a command like `pip` or `easy_install`).
|
||||
|
||||
* Set the `pluginpath` config variable to point to the directory containing the
|
||||
plugin. (See :doc:`/reference/config`.)
|
||||
|
||||
Once the plugin is installed, enable it by placing its name on the `plugins`
|
||||
line in your config file.
|
||||
|
||||
Here are a few of the plugins written by the beets community:
|
||||
|
||||
* `beetFs`_ is a FUSE filesystem for browsing the music in your beets library.
|
||||
|
|
@ -145,24 +139,9 @@ Here are a few of the plugins written by the beets community:
|
|||
|
||||
* `A cmus plugin`_ integrates with the `cmus`_ console music player.
|
||||
|
||||
* `featInTitle`_ moves featured artists from the artist tag to the title tag.
|
||||
|
||||
.. _beetFs: http://code.google.com/p/beetfs/
|
||||
.. _Beet-MusicBrainz-Collection:
|
||||
https://github.com/jeffayle/Beet-MusicBrainz-Collection/
|
||||
.. _A cmus plugin:
|
||||
https://github.com/coolkehon/beets/blob/master/beetsplug/cmus.py
|
||||
.. _cmus: http://cmus.sourceforge.net/
|
||||
.. _featInTitle: https://github.com/Verrus/beets-plugin-featInTitle/
|
||||
|
||||
Writing Plugins
|
||||
---------------
|
||||
|
||||
If you know a little Python, you can write your own plugin to do almost anything
|
||||
you can imagine with your music collection. See the :doc:`guide to writing beets
|
||||
plugins </plugins/writing>`.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
writing
|
||||
|
|
|
|||
Loading…
Reference in a new issue