Metadata-Version: 2.4
Name: Mopidy-Bookmarks
Version: 0.2.0rc1
Summary: Provides bookmarks functionalities to mopidy.
Author-email: Mathias Millet <mathiasmillet@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/sapristi/mopidy-bookmarks
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: Mopidy>=3.0.0
Requires-Dist: Pykka>=2.0.1
Requires-Dist: setuptools
Requires-Dist: peewee>=3.10.0
Provides-Extra: lint
Requires-Dist: check-manifest; extra == "lint"
Requires-Dist: pre-commit; extra == "lint"
Requires-Dist: ruff; extra == "lint"
Provides-Extra: release
Requires-Dist: twine; extra == "release"
Requires-Dist: wheel; extra == "release"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: tox; extra == "test"
Provides-Extra: dev
Requires-Dist: Mopidy-Bookmarks[lint,release,test]; extra == "dev"
Dynamic: license-file

****************************
Mopidy-Bookmarks
****************************

.. image:: https://img.shields.io/pypi/v/Mopidy-Bookmarks
    :target: https://pypi.org/project/Mopidy-Bookmarks/
    :alt: Latest PyPI version

.. image:: https://github.com/sapristi/mopidy-bookmarks/actions/workflows/python-package.yml/badge.svg
    :target: https://github.com/sapristi/mopidy-bookmarks/actions/workflows/python-package.yml
    :alt: CI build status

Provides bookmarks functionalities to mopidy.

Bookmarks are playlist that can be synced with the current playback state, so that you can easily stop listening to some tracklist, listen to something else, and later resume at the position where you stopped. This is most usefull when listening to audiobooks.

This extension can only be used with a compatible mopidy client. For now, only `mopidy-mowecl`_ is compatible.

.. _mopidy-mowecl: https://mopidy.com/ext/mowecl/

Inner design and operation
==========================

Bookmarks are exposed as regular mopidy playlists, under the `bookmark:` uri.

A websocket interface gives additional control:

- start syncing the current tracklist with a bookmark, i.e. store current track and time along with the playlist.
- resume a given bookmark (i.e. restore tracklist and start playing).
- stop the syncing.


When synchronising between a bookmark and playback state, the current track and current time will be saved periodically (every 0.5 second by default). As soon as the tracklist changes, or the ``stop_sync`` command is received, synchronisation will stop.

All the data is stored in a sqlite database.

Usage
=====

Access to the bookmarks API is provided by a websocket server, which works in exactly the same way as the mopidy websocket server. It can thus be used with the `Mopidy-js client`_ by connecting to the address ``mopidy-host:port/bookmarks/ws``.



1. Create the clients

    .. code-block:: javascript

        const mopidyClient = new Mopidy({
          webSocketUrl: "ws://localhost:6680/mopidy/ws/",
        });
        const bookmarksClient = new Mopidy({
          webSocketUrl: "ws://localhost:6680/bookmarks/ws/",
        });

2. To create a bookmark, simply create a new playlist (here from current tracklist):

    .. code-block:: javascript

        const BookmarkName = "my bookmark";
        const tracks = await mopidyClient.tracklist.getTracks();
        const BMPlaylist = await mopidyClient.playlists.create({
            name: BookmarkName,
            uri_scheme: "bookmark",
          })
        BMPlaylist.tracks = tracks;
        await mopidyClient.play.save({playlist: BMPlaylist})

3. You can then start syncronisation:

    .. code-block:: javascript

        bookmarksClient.startSync({uri: BMPlaylist.uri })

3. Stop synchronisation manually at any time:

    .. code-block:: javascript

        bookmarksClient.stopSync()

5. And restore tracklist and playback state with the resume command:

    .. code-block:: javascript

        bookmarksClient.resume({uri: BMPlaylist.uri })



6. Finally, you can react to change in synchronisation status with the following:
    .. code-block:: javascript

      bookmarksClient.on("event:syncStatusUpdate", (newStatus) => ... )

.. _Mopidy-js Client: https://github.com/mopidy/mopidy.js


API
===

Commands
--------

``start_sync(uri)``:   Starts syncing the given bookmark with the playback state.

    The tracklist must correspond to the tracks of the bookmark.

    *Parameters*
    
    uri : str
        The uri of the bookmark to resume

    *Returns*
    
    bool
        ``True`` if syncing started, else ``False``
 
``resume(uri)``:   Resumes playback from a bookmark.

    Populates the tracklist with the tracks of the bookmark, resumes playback from
    the saved position and sync the bookmark with the current playback state (track and time).

    *Parameters*
    
    uri : str
        The uri of the bookmark to resume

    *Returns*
    
    bool
        ``True`` if a bookmark was found for the given uri, else ``False``
 
``get_current_bookmark()``: Get the current synced bookmark if any.

    *Returns*
    
    mopidy.models.Ref or None
        A ref to the current bookmark if any, else None

``stop_sync()``:   Stop syncing the current bookmark.

Events
------

``sync_status_update``: When sync status changes.

    The event payload is an object of the form ``{bookmark: data}``, where ``data`` is the name of the bookmark being synchronised, or ``null`` if synchronisation has stopped.



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

Install by running::

    python3 -m pip install Mopidy-Bookmarks

Note that this extension is a dependency of ``mopidy-mowecl``, so it will already be installed if you are using this client.


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

Mopidy-Bookmarks provides the following configuration keys (and their default values). ::

      [bookmarks]
      enabled = true

      # sync period, in milliseconds
      sync_period = 500

      # set this to false to enable limits defined below
      # (usefull if mopidy listens on a public network e.g.)
      disable_limits = true
      # max number of bookmarks
      max_bookmarks = 100
      # max size of data for one bookmark
      max_bookmark_length = 100000

      # max number of items in store
      max_store_items = 10
      # max store item length
      max_store_item_length = 1000

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

- `Source code <https://github.com/sapristi/mopidy-bookmarks>`_
- `Issue tracker <https://github.com/sapristi/mopidy-bookmarks/issues>`_
- `Changelog <https://github.com/sapristi/mopidy-bookmarks/blob/master/CHANGELOG.rst>`_


Credits
=======

- Original author: `Mathias Millet <https://github.com/sapristi>`__
- Current maintainer: `Mathias Millet <https://github.com/sapristi>`__
- `Contributors <https://github.com/sapristi/mopidy-bookmarks/graphs/contributors>`_
