************
Mopidy-Local
************
.. image:: https://img.shields.io/pypi/v/Mopidy-Local
:target: https://pypi.org/project/Mopidy-Local/
:alt: Latest PyPI version
.. image:: https://img.shields.io/github/actions/workflow/status/mopidy/mopidy-local/ci.yml?branch=main
:target: https://github.com/mopidy/mopidy-local/actions
:alt: CI build status
.. image:: https://img.shields.io/codecov/c/gh/mopidy/mopidy-local
:target: https://codecov.io/gh/mopidy/mopidy-local
:alt: Test coverage
`Mopidy`_ extension for playing music from your local music archive.
.. _Mopidy: https://www.mopidy.com/
Table of contents
=================
- `Maintainer wanted`_
- Installation_
- Configuration_
- Usage_
- `Generating a library`_
- `Updating the library`_
- `Clearing the library`_
- `Library layout`_
- `Project resources`_
- Credits_
Maintainer wanted
=================
Mopidy-Local is currently kept on life support by the Mopidy core
developers. It is in need of a more dedicated maintainer.
If you want to be the maintainer of Mopidy-Local, please:
1. Make 2-3 good pull requests improving any part of the project.
2. Read and get familiar with all of the project's open issues.
3. Send a pull request removing this section and adding yourself as the
"Current maintainer" in the "Credits" section below. In the pull request
description, please refer to the previous pull requests and state that
you've familiarized yourself with the open issues.
As a maintainer, you'll be given push access to the repo and the authority to
make releases to PyPI when you see fit.
Installation
============
Install by running::
sudo python3 -m pip install Mopidy-Local
See https://mopidy.com/ext/local/ for alternative installation methods.
Configuration
=============
Before starting Mopidy, you must add configuration for
Mopidy-Local to your Mopidy configuration file::
[local]
media_dir = /path/to/your/music/archive
The following configuration values are available:
- ``local/enabled``: If the local extension should be enabled or not.
Defaults to ``true``.
- ``local/media_dir``: Path to directory with local media files.
- ``local/max_search_results``: Number of search results that should be returned. Default is 100.
- ``local/scan_timeout``: Number of milliseconds before giving up scanning a
file and moving on to the next file.
- ``local/scan_follow_symlinks``: If we should follow symlinks found in
``local/media_dir``.
- ``local/scan_flush_threshold``: Number of tracks to wait before telling
library it should try and store its progress so far. Some libraries might not
respect this setting. Set this to zero to disable flushing.
- ``local/included_file_extensions``: File extensions to include when scanning
the media directory. Values should be separated by either comma or newline.
Each file extension should start with a dot, .e.g. ``.flac``. Setting any
values here will override the existence of ``local/excluded_file_extensions``.
- ``local/excluded_file_extensions``: File extensions to exclude when scanning
the media directory. Values should be separated by either comma or newline.
Each file extension should start with a dot, .e.g. ``.html``. Defaults to a
list of common non-audio file extensions often found in music collections.
This config value has no effect if ``local/included_file_extensions`` is set.
- ``local/directories``: List of top-level directory names and URIs
for browsing. See below.
- ``local/timeout``: Database connection timeout in seconds.
- ``local/use_artist_sortname``: Whether to use the sortname field for
ordering artist browse results. Disabled by default, since this may
give confusing results if not all artists in the library have proper
sortnames.
- ``local/album_art_files``: List of file names to check for when searching
for external album art. These may contain UNIX shell patterns,
i.e. ``*``, ``?``, etc.
Usage
=====
Generating a library
--------------------
The command ``mopidy local scan`` will scan the path set in the
``local/media_dir`` config value for any audio files and build a
library of metadata.
To make a local library for your music available for Mopidy:
#. Ensure that the ``local/media_dir`` config value points to where your
music is located. Check the current setting by running::
mopidy config
#. Scan your media library.::
mopidy local scan
#. Start Mopidy, find the music library in a client, and play some local music!
Updating the library
--------------------
When you've added or removed music in your collection and want to update
Mopidy's index of your local library, you need to rescan::
mopidy local scan
Options can be specified to control the behavior of the scan command:
- ``--force`` Force rescan of all media files
- ``--limit <number>`` Maximum number of tracks to scan
Example::
mopidy local scan --limit 50
Clearing the library
--------------------
To delete your local images and clear your local library::
mopidy local clear
A prompt will ask you to confirm this irreversible operation.
Library layout
--------------
The exposed library has a root directory and nine top-level directories defined
under the root directory:
- Albums
- Artists
- Composers
- Genres
- Performers
- Release Years
- Tracks
- Last Week's Updates
- Last Month's Updates
This can be configured through the ``directories`` setting. It's expected to be a
list of space separated name and URI supported for browsing, eg::
directories =
Albums local:directory?type=album
Artists local:directory?type=artist
Composers local:directory?type=artist&role=composer
Tracks local:directory?type=track
Last Week's Updates local:directory?max-age=604800
URIs supported for browsing
~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Remember that URIs are opaque values that neither Mopidy’s core layer or Mopidy
frontends should attempt to derive any meaning from.* That said, it's necessary
to have a sufficient knowledge of Mopidy-Local URIs to customize the
``directories`` setting properly.
Browsing URIs starting with ``local:artist`` returns references to
albums and tracks with the given artist. Browsing URIs starting with
``local:album`` returns references to the album tracks. Browsing URIs
starting with ``local:track`` is not supported.
Other URIs supported for browsing start with ``local:directory``. The returned
references are specified through "query parameters":
- ``local:directory``: References to the top levels directories.
- ``local:directory?type=tracks``: References all tracks. Multiple
parameters can be added to filter the referenced tracks: ``album``,
``albumartist``, ``artist``, ``composer``, ``date``, ``genre``,
``performer``, and ``max-age``.
- ``local:directory?type=date``: References to directories grouping tracks by
date and album. Dates are transformed according to the optional parameter
``FORMAT`` which default to ``%Y-%m-%d``. The URIs of the references start
with ``local:directory?date=``.
- ``local:directory?type=genre``: References to directories named after genres
found among all tracks. Their URIs start with ``local:directory?genre=``.
- ``local:directory?type=album``: References to all albums.
- ``local:directory?type=album&PARAM=VALUE``: References to
directories grouping tracks matching the given criteria. ``PARAM``
must be one of ``albumartist``, ``artist``, ``composer``, ``date``,
``genre``, ``performer``, ``max-age``. The referenced directories
group the selected tracks by album; Their URIs start with
``local:directory?PARAM=VALUE&type=track&album=local:album:``.
- ``local:directory?type=artist``: References to all artists.
- ``local:directory?type=artist&role=ROLE``: References to directories with URIs
``local:directory?ROLE=URI`` where ``URI`` varies among all URIs starting with
``local:artist`` build from all tracks tag corresponding to ``ROLE``. ``ROLE``
is one of ``albumartist``, ``artist``, ``composer``, or ``performer``.
- ``local:directory?album=URI``: A reference to a directory grouping the tracks
of the album with given URI. Its URI starts with
``local:directory?album=URI&type=track``.
- ``local:directory?albumartist=URI``: References to directories
grouping tracks whose albumartist tag has given URI. The referenced
directories group the selected tracks by album; Their URIs start
with
``local:directory?albumartist=URI&type=track&album=local:album:``.
- ``local:directory?artist=URI``: References to directories grouping
tracks whose artist has given URI. The referenced directories group
the selected tracks by album; Their URIs start with
``local:directory?artist=URI&type=track&album=local:album:``.
- ``local:directory?composer=URI``: References to directories grouping
tracks whose composer has given URI. The referenced directories
group the selected tracks by album; Their URIs start with
``local:directory?composer=URI&type=track&album=local:album:``.
- ``local:directory?date=DATE``: References to directories grouping
tracks whose date match DATE. The referenced directories group the
selected tracks by album; Their URIs start with
``local:directory?date=DATE&type=track&album=local:album:``. The
match is to be interpreted as in a ``LIKE`` SQL statement.
- ``local:directory?genre=GENRE``: References to directories grouping
tracks whose genre is GENRE. The referenced directories group the
selected tracks by album; Their URIs start with
``local:directory?genre=GENRE&type=track&album=local:album:``.
- ``local:directory?performer=URI``: References to directories
grouping tracks whose performer has given URI. The referenced
directories group the selected tracks by album; Their URIs start
with
``local:directory?performer=URI&type=track&album=local:album:``.
- ``local:directory?max-age=SECONDS``: References to directories
grouping tracks whose "last modified" date is newer than SECONDS
seconds. The referenced directories group the selected tracks by
album; Their URIs start with
``local:directory?max-age=SECONDS&type=track&album=local:album:``.
Project resources
=================
- `Source code <https://github.com/mopidy/mopidy-local>`_
- `Issue tracker <https://github.com/mopidy/mopidy-local/issues>`_
- `Changelog <https://github.com/mopidy/mopidy-local/releases>`_
Credits
=======
- Original authors:
`Stein Magnus Jodal <https://github.com/jodal>`__ and
`Thomas Adamcik <https://github.com/adamcik>`__ for the Mopidy-Local extension in Mopidy core.
`Thomas Kemmer <https://github.com/tkem>`__ for the SQLite storage and support for embedded album art.
- Current maintainer: None. Maintainer wanted, see section above.
- `Contributors <https://github.com/mopidy/mopidy-local/graphs/contributors>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/mopidy/mopidy-local",
"name": "mopidy-local",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Stein Magnus Jodal",
"author_email": "stein.magnus@jodal.no",
"download_url": "https://files.pythonhosted.org/packages/02/c5/d099a05df7d6b0687071aa7d2d7a3499802b3b4b641531cd46ec8e6e7035/mopidy_local-3.3.0.tar.gz",
"platform": null,
"description": "************\nMopidy-Local\n************\n\n.. image:: https://img.shields.io/pypi/v/Mopidy-Local\n :target: https://pypi.org/project/Mopidy-Local/\n :alt: Latest PyPI version\n\n.. image:: https://img.shields.io/github/actions/workflow/status/mopidy/mopidy-local/ci.yml?branch=main\n :target: https://github.com/mopidy/mopidy-local/actions\n :alt: CI build status\n\n.. image:: https://img.shields.io/codecov/c/gh/mopidy/mopidy-local\n :target: https://codecov.io/gh/mopidy/mopidy-local\n :alt: Test coverage\n\n`Mopidy`_ extension for playing music from your local music archive.\n\n.. _Mopidy: https://www.mopidy.com/\n\n\nTable of contents\n=================\n\n- `Maintainer wanted`_\n- Installation_\n- Configuration_\n- Usage_\n\n - `Generating a library`_\n - `Updating the library`_\n - `Clearing the library`_\n - `Library layout`_\n\n- `Project resources`_\n- Credits_\n\n\nMaintainer wanted\n=================\n\nMopidy-Local is currently kept on life support by the Mopidy core\ndevelopers. It is in need of a more dedicated maintainer.\n\nIf you want to be the maintainer of Mopidy-Local, please:\n\n1. Make 2-3 good pull requests improving any part of the project.\n\n2. Read and get familiar with all of the project's open issues.\n\n3. Send a pull request removing this section and adding yourself as the\n \"Current maintainer\" in the \"Credits\" section below. In the pull request\n description, please refer to the previous pull requests and state that\n you've familiarized yourself with the open issues.\n\n As a maintainer, you'll be given push access to the repo and the authority to\n make releases to PyPI when you see fit.\n\n\nInstallation\n============\n\nInstall by running::\n\n sudo python3 -m pip install Mopidy-Local\n\nSee https://mopidy.com/ext/local/ for alternative installation methods.\n\n\nConfiguration\n=============\n\nBefore starting Mopidy, you must add configuration for\nMopidy-Local to your Mopidy configuration file::\n\n [local]\n media_dir = /path/to/your/music/archive\n\nThe following configuration values are available:\n\n- ``local/enabled``: If the local extension should be enabled or not.\n Defaults to ``true``.\n\n- ``local/media_dir``: Path to directory with local media files.\n\n- ``local/max_search_results``: Number of search results that should be returned. Default is 100.\n\n- ``local/scan_timeout``: Number of milliseconds before giving up scanning a\n file and moving on to the next file.\n\n- ``local/scan_follow_symlinks``: If we should follow symlinks found in\n ``local/media_dir``.\n\n- ``local/scan_flush_threshold``: Number of tracks to wait before telling\n library it should try and store its progress so far. Some libraries might not\n respect this setting. Set this to zero to disable flushing.\n\n- ``local/included_file_extensions``: File extensions to include when scanning\n the media directory. Values should be separated by either comma or newline.\n Each file extension should start with a dot, .e.g. ``.flac``. Setting any\n values here will override the existence of ``local/excluded_file_extensions``.\n\n- ``local/excluded_file_extensions``: File extensions to exclude when scanning\n the media directory. Values should be separated by either comma or newline.\n Each file extension should start with a dot, .e.g. ``.html``. Defaults to a\n list of common non-audio file extensions often found in music collections.\n This config value has no effect if ``local/included_file_extensions`` is set.\n\n- ``local/directories``: List of top-level directory names and URIs\n for browsing. See below.\n\n- ``local/timeout``: Database connection timeout in seconds.\n\n- ``local/use_artist_sortname``: Whether to use the sortname field for\n ordering artist browse results. Disabled by default, since this may\n give confusing results if not all artists in the library have proper\n sortnames.\n\n- ``local/album_art_files``: List of file names to check for when searching\n for external album art. These may contain UNIX shell patterns,\n i.e. ``*``, ``?``, etc.\n\n\nUsage\n=====\n\n\nGenerating a library\n--------------------\n\nThe command ``mopidy local scan`` will scan the path set in the\n``local/media_dir`` config value for any audio files and build a\nlibrary of metadata.\n\nTo make a local library for your music available for Mopidy:\n\n#. Ensure that the ``local/media_dir`` config value points to where your\n music is located. Check the current setting by running::\n\n mopidy config\n\n#. Scan your media library.::\n\n mopidy local scan\n\n#. Start Mopidy, find the music library in a client, and play some local music!\n\n\nUpdating the library\n--------------------\n\nWhen you've added or removed music in your collection and want to update\nMopidy's index of your local library, you need to rescan::\n\n mopidy local scan\n\nOptions can be specified to control the behavior of the scan command:\n\n- ``--force`` Force rescan of all media files\n- ``--limit <number>`` Maximum number of tracks to scan\n\nExample::\n\n mopidy local scan --limit 50\n\n\nClearing the library\n--------------------\n\nTo delete your local images and clear your local library::\n\n mopidy local clear\n\nA prompt will ask you to confirm this irreversible operation.\n\n\nLibrary layout\n--------------\n\nThe exposed library has a root directory and nine top-level directories defined\nunder the root directory:\n\n- Albums\n- Artists\n- Composers\n- Genres\n- Performers\n- Release Years\n- Tracks\n- Last Week's Updates\n- Last Month's Updates\n\nThis can be configured through the ``directories`` setting. It's expected to be a\nlist of space separated name and URI supported for browsing, eg::\n\n directories =\n Albums local:directory?type=album\n Artists local:directory?type=artist\n Composers local:directory?type=artist&role=composer\n Tracks local:directory?type=track\n Last Week's Updates local:directory?max-age=604800\n\nURIs supported for browsing\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n*Remember that URIs are opaque values that neither Mopidy\u2019s core layer or Mopidy\nfrontends should attempt to derive any meaning from.* That said, it's necessary\nto have a sufficient knowledge of Mopidy-Local URIs to customize the\n``directories`` setting properly.\n\nBrowsing URIs starting with ``local:artist`` returns references to\nalbums and tracks with the given artist. Browsing URIs starting with\n``local:album`` returns references to the album tracks. Browsing URIs\nstarting with ``local:track`` is not supported.\n\nOther URIs supported for browsing start with ``local:directory``. The returned\nreferences are specified through \"query parameters\":\n\n- ``local:directory``: References to the top levels directories.\n\n- ``local:directory?type=tracks``: References all tracks. Multiple\n parameters can be added to filter the referenced tracks: ``album``,\n ``albumartist``, ``artist``, ``composer``, ``date``, ``genre``,\n ``performer``, and ``max-age``.\n\n- ``local:directory?type=date``: References to directories grouping tracks by\n date and album. Dates are transformed according to the optional parameter\n ``FORMAT`` which default to ``%Y-%m-%d``. The URIs of the references start\n with ``local:directory?date=``.\n\n- ``local:directory?type=genre``: References to directories named after genres\n found among all tracks. Their URIs start with ``local:directory?genre=``.\n\n- ``local:directory?type=album``: References to all albums.\n\n- ``local:directory?type=album&PARAM=VALUE``: References to\n directories grouping tracks matching the given criteria. ``PARAM``\n must be one of ``albumartist``, ``artist``, ``composer``, ``date``,\n ``genre``, ``performer``, ``max-age``. The referenced directories\n group the selected tracks by album; Their URIs start with\n ``local:directory?PARAM=VALUE&type=track&album=local:album:``.\n\n- ``local:directory?type=artist``: References to all artists.\n\n- ``local:directory?type=artist&role=ROLE``: References to directories with URIs\n ``local:directory?ROLE=URI`` where ``URI`` varies among all URIs starting with\n ``local:artist`` build from all tracks tag corresponding to ``ROLE``. ``ROLE``\n is one of ``albumartist``, ``artist``, ``composer``, or ``performer``.\n\n- ``local:directory?album=URI``: A reference to a directory grouping the tracks\n of the album with given URI. Its URI starts with\n ``local:directory?album=URI&type=track``.\n\n- ``local:directory?albumartist=URI``: References to directories\n grouping tracks whose albumartist tag has given URI. The referenced\n directories group the selected tracks by album; Their URIs start\n with\n ``local:directory?albumartist=URI&type=track&album=local:album:``.\n\n- ``local:directory?artist=URI``: References to directories grouping\n tracks whose artist has given URI. The referenced directories group\n the selected tracks by album; Their URIs start with\n ``local:directory?artist=URI&type=track&album=local:album:``.\n\n- ``local:directory?composer=URI``: References to directories grouping\n tracks whose composer has given URI. The referenced directories\n group the selected tracks by album; Their URIs start with\n ``local:directory?composer=URI&type=track&album=local:album:``.\n\n- ``local:directory?date=DATE``: References to directories grouping\n tracks whose date match DATE. The referenced directories group the\n selected tracks by album; Their URIs start with\n ``local:directory?date=DATE&type=track&album=local:album:``. The\n match is to be interpreted as in a ``LIKE`` SQL statement.\n\n- ``local:directory?genre=GENRE``: References to directories grouping\n tracks whose genre is GENRE. The referenced directories group the\n selected tracks by album; Their URIs start with\n ``local:directory?genre=GENRE&type=track&album=local:album:``.\n\n- ``local:directory?performer=URI``: References to directories\n grouping tracks whose performer has given URI. The referenced\n directories group the selected tracks by album; Their URIs start\n with\n ``local:directory?performer=URI&type=track&album=local:album:``.\n\n- ``local:directory?max-age=SECONDS``: References to directories\n grouping tracks whose \"last modified\" date is newer than SECONDS\n seconds. The referenced directories group the selected tracks by\n album; Their URIs start with\n ``local:directory?max-age=SECONDS&type=track&album=local:album:``.\n\nProject resources\n=================\n\n- `Source code <https://github.com/mopidy/mopidy-local>`_\n- `Issue tracker <https://github.com/mopidy/mopidy-local/issues>`_\n- `Changelog <https://github.com/mopidy/mopidy-local/releases>`_\n\n\nCredits\n=======\n\n- Original authors:\n `Stein Magnus Jodal <https://github.com/jodal>`__ and\n `Thomas Adamcik <https://github.com/adamcik>`__ for the Mopidy-Local extension in Mopidy core.\n `Thomas Kemmer <https://github.com/tkem>`__ for the SQLite storage and support for embedded album art.\n- Current maintainer: None. Maintainer wanted, see section above.\n- `Contributors <https://github.com/mopidy/mopidy-local/graphs/contributors>`_\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Mopidy extension for playing music from your local music archive",
"version": "3.3.0",
"project_urls": {
"Homepage": "https://github.com/mopidy/mopidy-local"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7eed38ba58e3003fb815206acb47fcd5fa8c1c0c3b70f0100c5269f847d9314e",
"md5": "7a1113b5ded929c92773a4039178e9fb",
"sha256": "6b6581be2136058780d9ea40495b54f288d89de4d012eb8a6b8ddc7324153b18"
},
"downloads": -1,
"filename": "Mopidy_Local-3.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a1113b5ded929c92773a4039178e9fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 32342,
"upload_time": "2024-12-17T23:15:45",
"upload_time_iso_8601": "2024-12-17T23:15:45.410942Z",
"url": "https://files.pythonhosted.org/packages/7e/ed/38ba58e3003fb815206acb47fcd5fa8c1c0c3b70f0100c5269f847d9314e/Mopidy_Local-3.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "02c5d099a05df7d6b0687071aa7d2d7a3499802b3b4b641531cd46ec8e6e7035",
"md5": "93e33849bc859b370fadaab28aa0a804",
"sha256": "cba6ed6c693952255a9f5efcc7b77d8eae4e4e728c6ee9621efd1a471b992b7a"
},
"downloads": -1,
"filename": "mopidy_local-3.3.0.tar.gz",
"has_sig": false,
"md5_digest": "93e33849bc859b370fadaab28aa0a804",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 39180,
"upload_time": "2024-12-17T23:15:47",
"upload_time_iso_8601": "2024-12-17T23:15:47.889501Z",
"url": "https://files.pythonhosted.org/packages/02/c5/d099a05df7d6b0687071aa7d2d7a3499802b3b4b641531cd46ec8e6e7035/mopidy_local-3.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 23:15:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mopidy",
"github_project": "mopidy-local",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mopidy-local"
}
JSON
