Mopidy-Webhooks
===============

`Mopidy <https://www.mopidy.com/>`_ extension for sending mopidy play status to
arbitrary URL endpoints

Installation
============

Install by running::

    sudo python3 -m pip install Mopidy-Webhooks


Configuration
=============

To enable this extension, make sure to add the following variables to your
Mopidy configuration file. Note that multiple URLs can be sent to by separating
them with a comma. Tokens match the listing of urls::

    [webhooks]
    enabled = true
    urls = https://example.com/api/receiver/,http://127.0.0.1:8000/webhook/
    tokens = ,2349080989234089
    media_dirs = /var/lib/mopidy/media
    podcast_dirs = /var/lib/mopidy/media/podcasts

The following configuration values are available:

- ``webhooks/enabled``: If the webhooks extension should be enabled or not.
  Defaults to disabled.
- ``webhooks/urls``: Comma-separated list of endpoints to send play data to
- ``webhooks/tokens``: Comma-separated list of tokens to send in the
  Authorization header for each URL
- ``webhooks/media_dirs``: Comma-separated list of local media roots used to
  resolve ``local:track:``/``local:podcast:`` URIs to files so their tags can
  be read. Defaults to ``/var/lib/mopidy/media``.
- ``webhooks/podcast_dirs``: Comma-separated list of directories that should
  always be treated as podcasts, even when the URI does not mention it.


Podcast metadata
================

When a track is detected as a podcast episode, the webhook payload is enriched
with metadata read from the audio file itself, so the receiver no longer has to
guess the podcast, episode number or publication date from the file name.

Sources, in order of preference:

1. Audio tags (ID3, Vorbis, MP4) read with `mutagen
   <https://mutagen.readthedocs.io/>`_: title, artist, album, track number,
   date, genre, comment/description, publisher, language, copyright and
   website.
2. A sidecar JSON file written next to the episode (``<episode>.json``) or in
   a ``metadata/`` directory (``metadata/<episode>.json``), as produced by
   common podcatchers. This provides ``feed_url``, ``guid``, ``episode_url``,
   ``duration``, ``image`` and a fallback ``description``.

Podcast episodes are detected when the URI contains ``podcast``, when the file
lives under one of the ``webhooks/podcast_dirs``, or when the file has a
sidecar JSON with a feed URL or guid.

In addition to the regular fields, podcast payloads include:

- ``media_type``: ``"podcast"`` or ``"track"``
- ``podcast_name``, ``podcast_producer``, ``podcast_description``
- ``podcast_feed_url``, ``podcast_site_link``
- ``episode_num``, ``pub_date`` (``YYYY-MM-DD``)
- ``episode_description``, ``episode_url``, ``episode_guid``


Project resources
=================

- `Source code <https://code.unbl.ink/secstate/mopidy-webhooks>`_
- `Issue tracker <https://code.unbl.ink/secstate/mopidy-webhooks/issues>`_
- `Changelog <https://code.unbl.ink/secstate/mopidy-webhooks/releases>`_


Credits
=======

- Author: `Colin Powell <https://github.com/powellc>`__