mirror of
https://github.com/beetbox/beets.git
synced 2025-12-07 09:04:33 +01:00
77 lines
3 KiB
ReStructuredText
77 lines
3 KiB
ReStructuredText
Hook Plugin
|
|
===============
|
|
|
|
Internally, beets sends events to plugins when an action finishes. These can
|
|
range from importing a song (``import``) to beets exiting (``cli_exit``), and
|
|
provide a very flexible way to perform actions based on the events. This plugin
|
|
allows you to run commands when an event is emitted by beets, such as syncing
|
|
your library with another drive when the library is updated.
|
|
|
|
Hooks are currently run in the order defined in the configuration, however this
|
|
is dependent on beets itself (may change in the future) and cannot be controlled
|
|
by this plugin.
|
|
|
|
.. _hook-configuration:
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
To configure the plugin, make a ``hook:`` section in your configuration
|
|
file. The available options are:
|
|
|
|
- **hooks**: A list of events and the commands to run (see :ref:`individual-hook-configuration`)
|
|
Default: Empty.
|
|
- **substitute_event**: The string to replace in each command with the name of
|
|
the event executing it. This can be used to allow one script to act
|
|
differently depending on the event it was called by. Can be individually
|
|
overridden (see :ref:`individual-hook-configuration`).
|
|
Default: ``%EVENT%``
|
|
- **shell**: Run each command in a shell. Can be individually overridden (see
|
|
:ref:`individual-hook-configuration`).
|
|
Default: ``yes``
|
|
|
|
.. _individual-hook-configuration:
|
|
|
|
Individual Hook Configuration
|
|
-----------------------------
|
|
|
|
Each element of the ``hooks`` configuration option can be configured separately.
|
|
The available options are:
|
|
|
|
- **event** (required): The name of the event that should cause this hook to execute. See
|
|
:ref:`Plugin Events <plugin_events>` for a list of possible values.
|
|
- **command** (required): The command to run when this hook executes.
|
|
- **substitute_event**: Hook-level override for ``substitute_event`` option in
|
|
:ref:`hook-configuration`.
|
|
Default: Value of top level ``substitute_event`` option (see :ref:`hook-configuration`)
|
|
- **shell**: Hook-level override for ``shell`` option in :ref:`hook-configuration`.
|
|
Default: Value of top level ``shell`` option (see :ref:`hook-configuration`).
|
|
- **substitute_args**: A key/value set where the key is the name of the an
|
|
argument passed to the event (see :ref:`Plugin Events <plugin_events>` for
|
|
a list of arguments for each event) and the value is the string to replace
|
|
in the command with the value of the argument. Note that any arguments that
|
|
are not strings will be converted to strings (e.g. Python objects).
|
|
Default: Empty.
|
|
|
|
Example Configuration
|
|
---------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
hook:
|
|
hooks:
|
|
# Output on exit:
|
|
# beets just exited!
|
|
# have a nice day!
|
|
- event: cli_exit
|
|
command: echo "beets just exited!"
|
|
- event: cli_exit
|
|
command: echo "have a nice day!"
|
|
|
|
# Output on write
|
|
# writing to "<file_name_here>"
|
|
# Where <file_name_here> is the file being written to
|
|
- event: write
|
|
command echo "writing to \"%FILE_NAME%\""
|
|
substitute_args:
|
|
path: %FILE_NAME%
|