FLOZz Daily Mix
===============
|GitHub| |License| |Discord| |Github Actions| |Black|
FLOZz Daily Mix generates playlists similar to Spotify's Daily Mix from a Subsonic API.
This is currently a **work in progress** and it has only been tested against ownCloud / Nextcloud Music servers. Please note that only the legacy plain text password authentication is currently supported; that's why it will probably not work with most Subsonic servers.
This generator does not make completely random playlists but tries to build interesting ones. It adds "interesting" tracks regularly in the playlist (more at the beginning of the list and more spaced then). It also tries to put new/fresh tracks in at strategic places.
Here is an example of a generated playlist:
.. figure:: ./example-playlist.png
:target: ./example-playlist.png
:alt: Screenshot: Generated playlist
* **Yellow:** "interesting" tracks (criteria: high rating, liked,...)
* **Green:** "fresh" tracks (criteria: newly added, recently released, low play count,...)
* **Purple:** "back catalog" tracks (hasn't been played for a long time)
* **Blue:** "regular" tracks (random tracks with rate weighting)
Requirements
------------
This software only requires **Python >= 3.8**. There is no extra dependency.
Install
-------
Linux: from PyPI with venv
~~~~~~~~~~~~~~~~~~~~~~~~~~
To install FLOZz Daily Mix on Linux, the simplest way is to use the package from PyPI.
First be sure to have Python 3 installed with the venv module. On Debian / Ubuntu, you can achieve this with the following command::
sudo apt install python3 python3-venv
Then we can create the virtualenv to install the app::
python3 -m venv ./daily-mix.venv
And finally we can install FLOZz Daily Mix in the venv::
./daily-mix.venv/bin/pip install flozz-daily-mix
To run the software, just call its executable with a command like this::
./daily-mix.venv/bin/flozz-daily-mix --help
Configuration files
-------------------
To generate playlists with FLOZz Daily Mix, you should at least create one file with some information about the playlists. This file can also contain the Subsonic API settings and credential, but you will also be able to pass them later on the CLI.
Here is a commented example of a valid ``flozz-daily-mix.conf`` file:
.. code-block:: ini
[subsonic]
; URL of the Subsonic API.
; Can also be provieded using the --subsonic-api-url CLI option.
api_url = https://nextcloud.example.org/apps/music/subsonic
; Name of the Subsonic API user.
; Can also be provieded using the --subsonic-api-username CLI option.
api_username = foobar
; Password of the Subsonic API user.
; Can also be provieded using the --subsonic-api-password CLI option.
api_password = s3cr3tp4ssw0rd
; Use the Subsonic legacy (plaintext password) authentication method
; (default: false). By default this is turned off, but the legacy
; authentication is currently the only one supported so you must set it to
; "true".
api_legacy_authentication = true
; [playlist:<PLAYLIST_UNIQUE_ID>]
[playlist:mix1]
; Name of the playlist. Will be displayed by music clients (default: "Unnamed Mix")
name = FLOZz Mix 1
; An optional description for the playlist (default: "FLOZz Daily Mix")
description = FLOzz Daily Mix
; Maximum number of tracks in the playlist (default: 60).
max_tracks = 60
; Minimal duration of tracks included in the playlist in seconds (default: 60)
min_track_duration = 60
; Maximal duration of tracks included in the playlist in seconds (default: 600)
max_track_duration = 600
; Ignore tracks whose name matches the given regexp. The regexp are processed
; by Python `re` module and are case insensitive.
; Default: empty string (disables the filter)
ignore_tracks_matching = ^.*(intro(duction)?|instrumental|acoustic).*$
; Minimal rating for a track to be included in the playlist (from 1 to 5, default: 2)
minimal_tracks_rating = 2
; An other playlist
[playlist:mix2]
name = FLOZz Mix 2
description = FLOzz Daily Mix
max_tracks = 60
min_track_duration = 60
max_track_duration = 600
ignore_tracks_matching = ^.*(intro(duction)?|instrumental|acoustic).*$
minimal_tracks_rating = 2
Usage
-----
Once you have installed FLOZz Daily Mix and created a configuration file, you can start generating playlists.
**NOTE:** in this section I will use commands like ``flozz-daily-mix --help`` for readability, but if you installed FLOZz Daily Mix in a virtualenv as explained above, the command you should use will be something like ``/path/to/your/daily-mix.venv/bin/flozz-daily-mix --help``.
If your API credentials are configured in the file, you can generate your playlists with the following command::
flozz-daily-mix generate flozz-daily-mix.conf
If you do not wrote API configuration in the file, then the command will be a bit longer::
flozz-daily-mix \
--subsonic-api-url=https://nextcloud.example.org/apps/music/subsonic \
--subsonic-api-username=foobar \
--subsonic-api-password=s3cr3tp4ssw0rd \
--subsonic-api-legacy-authentication \
generate flozz-daily-mix.conf
**NOTE:** You can pass more than one configuration file, if you prefer writing one file per playlist.
You can also just generate and display playlists without writing them to the cloud::
flozz-daily-mix generate --dry-run --print-playlist flozz-daily-mix.conf
To get all available options, you can use the following commands::
flozz-daily-mix --help
flozz-daily-mix generate --help
flozz-daily-mix dumpdata --help # debug feature
Contributing
------------
Questions
~~~~~~~~~
If you have any question, you can:
* `Open an issue <https://github.com/flozz/daily-mix/issues>`_ on GitHub
* `Ask on Discord <https://discord.gg/P77sWhuSs4>`_ (I am not always available to chat, but I try to answer to everyone)
Bugs
~~~~
Please `open an issue <https://github.com/flozz/daily-mix/issues>`_ on GitHub with as much information as possible if you found a bug:
* Your operating system / Linux distribution (and its version)
* How you installed the software
* All the logs and message outputted by the software
* etc.
Pull requests
~~~~~~~~~~~~~
Please consider `filing a bug <https://github.com/flozz/daily-mix/issues>`_ before starting to work on a new feature; it will allow us to discuss the best way to do it. It is obviously unnecessary if you just want to fix a typo or small errors in the code.
Please note that your code must follow the coding style defined by the `pep8 <https://pep8.org>`_ and pass tests. `Black <https://black.readthedocs.io/en/stable>`_ and `Flake8 <https://flake8.pycqa.org/en/latest>`_ are used on this project to enforce the coding style.
Use a local database
~~~~~~~~~~~~~~~~~~~~
Reading data from the cloud API can be slow while developing. That's why it is possible to dump data to a file and to reuse it.
First dump the data (Subsonic API credential required)::
flozz-daily-mix dumpdata -c file-with-credentials.conf music.db
Then you can use the data with the ``generate`` command::
flozz-daily-mix generate --source-db=music.db --dry-run --print-playlist flozz-daily-mix.conf
**NOTE:** the command above does not require the API credential as it is both a dry-run (no write to the API) and we provide the data (no read from the API).
Run the tests
~~~~~~~~~~~~~
You must install `Nox <https://nox.thea.codes/>`__ first::
pip3 install nox
Then you can check for lint error::
nox --session lint
and run the tests::
nox --session test
You can use following commands to run the tests only on a certain Python version (the corresponding Python interpreter must be installed on your machine)::
nox --session test-3.8
nox --session test-3.9
nox --session test-3.10
nox --session test-3.11
nox --session test-3.12
You can also fix coding style errors automatically with::
nox -s black_fix
Support this project
--------------------
Want to support this project?
* `☕️ Buy me a coffee <https://www.buymeacoffee.com/flozz>`__
* `💵️ Give me a tip on PayPal <https://www.paypal.me/0xflozz>`__
* `❤️ Sponsor me on GitHub <https://github.com/sponsors/flozz>`__
Changelog
---------
* **[NEXT]** (changes on ``master`` that have not been released yet):
* Nothing yet ;)
* **v0.3.0:**
* feat: Added "back catalog" slots to generated playlists (@flozz)
* **v0.2.0:**
* feat: Improved logging and added ``--quiet`` and ``--verbose`` CLI options (@flozz)
* feat: Added an ``ignore_tracks_matching`` option to filter tracks whose name matches the given pattern (@flozz)
* feat: Output warning for wrong settings instead of ignoring them silently (@flozz)
* feat: Added a ``minimal_track_rating`` filter option (@flozz)
* fix: Add missing math functions when SQLite is not compiled with ``SQLITE_ENABLE_MATH_FUNCTIONS`` (@flozz)
* **v0.1.0:**
* feat: Get available musics from a Subsonic API, generate the playlists and write it to the API (@flozz)
* feat: Implemented command line interface (@flozz)
* feat: Implemented configuration file (@flozz)
* feat: Implemented basic debug features (data dump, print playlist, dry-run) (@flozz)
* docs: Initial basic documentation in the README (@flozz)
.. |GitHub| image:: https://img.shields.io/github/stars/flozz/daily-mix?label=GitHub&logo=github
:target: https://github.com/flozz/daily-mix
.. |License| image:: https://img.shields.io/github/license/flozz/daily-mix
:target: https://github.com/flozz/daily-mix/blob/master/COPYING
.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff
:target: https://discord.gg/P77sWhuSs4
.. |Github Actions| image:: https://github.com/flozz/daily-mix/actions/workflows/python-ci.yml/badge.svg
:target: https://github.com/flozz/daily-mix/actions
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://black.readthedocs.io/en/stable
Raw data
{
"_id": null,
"home_page": "https://github.com/flozz/daily-mix",
"name": "flozz-daily-mix",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "playlist subsonic owncloud nextcloud music",
"author": "Fabien LOISON",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a1/9e/5cb812318308f4223f2a8c095d7144e1f1ce01954591254f3999d0602fcc/flozz_daily_mix-0.3.0.tar.gz",
"platform": null,
"description": "FLOZz Daily Mix\n===============\n\n|GitHub| |License| |Discord| |Github Actions| |Black|\n\nFLOZz Daily Mix generates playlists similar to Spotify's Daily Mix from a Subsonic API.\n\nThis is currently a **work in progress** and it has only been tested against ownCloud\u00a0/ Nextcloud Music servers. Please note that only the legacy plain text password authentication is currently supported; that's why it will probably not work with most Subsonic servers.\n\nThis generator does not make completely random playlists but tries to build interesting ones. It adds \"interesting\" tracks regularly in the playlist (more at the beginning of the list and more spaced then). It also tries to put new/fresh tracks in at strategic places.\n\nHere is an example of a generated playlist:\n\n.. figure:: ./example-playlist.png\n :target: ./example-playlist.png\n :alt: Screenshot: Generated playlist\n\n* **Yellow:** \"interesting\" tracks (criteria: high rating, liked,...)\n* **Green:** \"fresh\" tracks (criteria: newly added, recently released, low play count,...)\n* **Purple:** \"back catalog\" tracks (hasn't been played for a long time)\n* **Blue:** \"regular\" tracks (random tracks with rate weighting)\n\n\nRequirements\n------------\n\nThis software only requires **Python >= 3.8**. There is no extra dependency.\n\n\nInstall\n-------\n\nLinux: from PyPI with venv\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo install FLOZz Daily Mix on Linux, the simplest way is to use the package from PyPI.\n\nFirst be sure to have Python 3 installed with the venv module. On Debian\u00a0/ Ubuntu, you can achieve this with the following command::\n\n sudo apt install python3 python3-venv\n\nThen we can create the virtualenv to install the app::\n\n python3 -m venv ./daily-mix.venv\n\nAnd finally we can install FLOZz Daily Mix in the venv::\n\n ./daily-mix.venv/bin/pip install flozz-daily-mix\n\nTo run the software, just call its executable with a command like this::\n\n ./daily-mix.venv/bin/flozz-daily-mix --help\n\n\nConfiguration files\n-------------------\n\nTo generate playlists with FLOZz Daily Mix, you should at least create one file with some information about the playlists. This file can also contain the Subsonic API settings and credential, but you will also be able to pass them later on the CLI.\n\nHere is a commented example of a valid ``flozz-daily-mix.conf`` file:\n\n.. code-block:: ini\n\n [subsonic]\n ; URL of the Subsonic API.\n ; Can also be provieded using the --subsonic-api-url CLI option.\n api_url = https://nextcloud.example.org/apps/music/subsonic\n ; Name of the Subsonic API user.\n ; Can also be provieded using the --subsonic-api-username CLI option.\n api_username = foobar\n ; Password of the Subsonic API user.\n ; Can also be provieded using the --subsonic-api-password CLI option.\n api_password = s3cr3tp4ssw0rd\n ; Use the Subsonic legacy (plaintext password) authentication method\n ; (default: false). By default this is turned off, but the legacy\n ; authentication is currently the only one supported so you must set it to\n ; \"true\".\n api_legacy_authentication = true\n\n ; [playlist:<PLAYLIST_UNIQUE_ID>]\n [playlist:mix1]\n ; Name of the playlist. Will be displayed by music clients (default: \"Unnamed Mix\")\n name = FLOZz Mix 1\n ; An optional description for the playlist (default: \"FLOZz Daily Mix\")\n description = FLOzz Daily Mix\n ; Maximum number of tracks in the playlist (default: 60).\n max_tracks = 60\n ; Minimal duration of tracks included in the playlist in seconds (default: 60)\n min_track_duration = 60\n ; Maximal duration of tracks included in the playlist in seconds (default: 600)\n max_track_duration = 600\n ; Ignore tracks whose name matches the given regexp. The regexp are processed\n ; by Python `re` module and are case insensitive.\n ; Default: empty string (disables the filter)\n ignore_tracks_matching = ^.*(intro(duction)?|instrumental|acoustic).*$\n ; Minimal rating for a track to be included in the playlist (from 1 to 5, default: 2)\n minimal_tracks_rating = 2\n\n ; An other playlist\n [playlist:mix2]\n name = FLOZz Mix 2\n description = FLOzz Daily Mix\n max_tracks = 60\n min_track_duration = 60\n max_track_duration = 600\n ignore_tracks_matching = ^.*(intro(duction)?|instrumental|acoustic).*$\n minimal_tracks_rating = 2\n\n\nUsage\n-----\n\nOnce you have installed FLOZz Daily Mix and created a configuration file, you can start generating playlists.\n\n**NOTE:** in this section I will use commands like ``flozz-daily-mix --help`` for readability, but if you installed FLOZz Daily Mix in a virtualenv as explained above, the command you should use will be something like ``/path/to/your/daily-mix.venv/bin/flozz-daily-mix --help``.\n\nIf your API credentials are configured in the file, you can generate your playlists with the following command::\n\n flozz-daily-mix generate flozz-daily-mix.conf\n\nIf you do not wrote API configuration in the file, then the command will be a bit longer::\n\n flozz-daily-mix \\\n --subsonic-api-url=https://nextcloud.example.org/apps/music/subsonic \\\n --subsonic-api-username=foobar \\\n --subsonic-api-password=s3cr3tp4ssw0rd \\\n --subsonic-api-legacy-authentication \\\n generate flozz-daily-mix.conf\n\n**NOTE:** You can pass more than one configuration file, if you prefer writing one file per playlist.\n\nYou can also just generate and display playlists without writing them to the cloud::\n\n flozz-daily-mix generate --dry-run --print-playlist flozz-daily-mix.conf\n\nTo get all available options, you can use the following commands::\n\n flozz-daily-mix --help\n flozz-daily-mix generate --help\n flozz-daily-mix dumpdata --help # debug feature\n\n\nContributing\n------------\n\nQuestions\n~~~~~~~~~\n\nIf you have any question, you can:\n\n* `Open an issue <https://github.com/flozz/daily-mix/issues>`_ on GitHub\n* `Ask on Discord <https://discord.gg/P77sWhuSs4>`_ (I am not always available to chat, but I try to answer to everyone)\n\n\nBugs\n~~~~\n\nPlease `open an issue <https://github.com/flozz/daily-mix/issues>`_ on GitHub with as much information as possible if you found a bug:\n\n* Your operating system\u00a0/ Linux distribution (and its version)\n* How you installed the software\n* All the logs and message outputted by the software\n* etc.\n\n\nPull requests\n~~~~~~~~~~~~~\n\nPlease consider `filing a bug <https://github.com/flozz/daily-mix/issues>`_ before starting to work on a new feature; it will allow us to discuss the best way to do it. It is obviously unnecessary if you just want to fix a typo or small errors in the code.\n\nPlease note that your code must follow the coding style defined by the `pep8 <https://pep8.org>`_ and pass tests. `Black <https://black.readthedocs.io/en/stable>`_ and `Flake8 <https://flake8.pycqa.org/en/latest>`_ are used on this project to enforce the coding style.\n\n\nUse a local database\n~~~~~~~~~~~~~~~~~~~~\n\nReading data from the cloud API can be slow while developing. That's why it is possible to dump data to a file and to reuse it.\n\nFirst dump the data (Subsonic API credential required)::\n\n flozz-daily-mix dumpdata -c file-with-credentials.conf music.db\n\nThen you can use the data with the ``generate`` command::\n\n flozz-daily-mix generate --source-db=music.db --dry-run --print-playlist flozz-daily-mix.conf\n\n**NOTE:** the command above does not require the API credential as it is both a dry-run (no write to the API) and we provide the data (no read from the API).\n\n\nRun the tests\n~~~~~~~~~~~~~\n\nYou must install `Nox <https://nox.thea.codes/>`__ first::\n\n pip3 install nox\n\nThen you can check for lint error::\n\n nox --session lint\n\nand run the tests::\n\n nox --session test\n\nYou can use following commands to run the tests only on a certain Python version (the corresponding Python interpreter must be installed on your machine)::\n\n nox --session test-3.8\n nox --session test-3.9\n nox --session test-3.10\n nox --session test-3.11\n nox --session test-3.12\n\nYou can also fix coding style errors automatically with::\n\n nox -s black_fix\n\n\nSupport this project\n--------------------\n\nWant to support this project?\n\n* `\u2615\ufe0f Buy me a coffee <https://www.buymeacoffee.com/flozz>`__\n* `\ud83d\udcb5\ufe0f Give me a tip on PayPal <https://www.paypal.me/0xflozz>`__\n* `\u2764\ufe0f Sponsor me on GitHub <https://github.com/sponsors/flozz>`__\n\n\nChangelog\n---------\n\n* **[NEXT]** (changes on ``master`` that have not been released yet):\n\n * Nothing yet ;)\n\n* **v0.3.0:**\n\n * feat: Added \"back catalog\" slots to generated playlists (@flozz)\n\n* **v0.2.0:**\n\n * feat: Improved logging and added ``--quiet`` and ``--verbose`` CLI options (@flozz)\n * feat: Added an ``ignore_tracks_matching`` option to filter tracks whose name matches the given pattern (@flozz)\n * feat: Output warning for wrong settings instead of ignoring them silently (@flozz)\n * feat: Added a ``minimal_track_rating`` filter option (@flozz)\n * fix: Add missing math functions when SQLite is not compiled with ``SQLITE_ENABLE_MATH_FUNCTIONS`` (@flozz)\n\n\n* **v0.1.0:**\n\n * feat: Get available musics from a Subsonic API, generate the playlists and write it to the API (@flozz)\n * feat: Implemented command line interface (@flozz)\n * feat: Implemented configuration file (@flozz)\n * feat: Implemented basic debug features (data dump, print playlist, dry-run) (@flozz)\n * docs: Initial basic documentation in the README (@flozz)\n\n\n.. |GitHub| image:: https://img.shields.io/github/stars/flozz/daily-mix?label=GitHub&logo=github\n :target: https://github.com/flozz/daily-mix\n\n.. |License| image:: https://img.shields.io/github/license/flozz/daily-mix\n :target: https://github.com/flozz/daily-mix/blob/master/COPYING\n\n.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff\n :target: https://discord.gg/P77sWhuSs4\n\n.. |Github Actions| image:: https://github.com/flozz/daily-mix/actions/workflows/python-ci.yml/badge.svg\n :target: https://github.com/flozz/daily-mix/actions\n\n.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://black.readthedocs.io/en/stable\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Generates thematic playlists like Spotify's Daily Mix from a Subsonic API",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/flozz/daily-mix?tab=readme-ov-file#changelog",
"Chat": "https://discord.gg/P77sWhuSs4",
"Documentation": "https://github.com/flozz/daily-mix/blob/master/README.rst",
"Donate": "https://github.com/flozz/daily-mix?tab=readme-ov-file#support-this-project",
"Homepage": "https://github.com/flozz/daily-mix",
"Issues": "https://github.com/flozz/daily-mix/issues",
"Source Code": "https://github.com/flozz/daily-mix"
},
"split_keywords": [
"playlist",
"subsonic",
"owncloud",
"nextcloud",
"music"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78903803312e1a9c72ab0583d846c42bb7beba980aadecd92c2b311d73999b84",
"md5": "739b0988dbd09afda973622c6a9f120a",
"sha256": "1e43c34923ce82b4603fea06c6c55dc7935afa4f37c65a151921494bec1bbc30"
},
"downloads": -1,
"filename": "flozz_daily_mix-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "739b0988dbd09afda973622c6a9f120a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28645,
"upload_time": "2024-09-11T11:18:21",
"upload_time_iso_8601": "2024-09-11T11:18:21.271375Z",
"url": "https://files.pythonhosted.org/packages/78/90/3803312e1a9c72ab0583d846c42bb7beba980aadecd92c2b311d73999b84/flozz_daily_mix-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a19e5cb812318308f4223f2a8c095d7144e1f1ce01954591254f3999d0602fcc",
"md5": "8b8974b08d30cf8ef4a6efa04bc5c2e4",
"sha256": "28dd53a6603a2a357026d10f069f015b29eced56fd9dcdbc0d01b27fe7d578c4"
},
"downloads": -1,
"filename": "flozz_daily_mix-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "8b8974b08d30cf8ef4a6efa04bc5c2e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 30307,
"upload_time": "2024-09-11T11:18:22",
"upload_time_iso_8601": "2024-09-11T11:18:22.617878Z",
"url": "https://files.pythonhosted.org/packages/a1/9e/5cb812318308f4223f2a8c095d7144e1f1ce01954591254f3999d0602fcc/flozz_daily_mix-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 11:18:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flozz",
"github_project": "daily-mix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flozz-daily-mix"
}
JSON
