From 975724a62e82ad513381b519377f90c54c4a0ee2 Mon Sep 17 00:00:00 2001 From: Kinuax Date: Sat, 11 May 2024 18:40:58 +0200 Subject: [PATCH] Migrate README from reStructuredText to Markdown --- README.md | 298 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 126 ---------------------- 2 files changed, 298 insertions(+), 126 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..87c9ffd --- /dev/null +++ b/README.md @@ -0,0 +1,298 @@ +# rolabesti - CLI app to manage, search, and play collections of mp3 tracks. + +[![Stable Version](https://img.shields.io/pypi/v/rolabesti?labelColor=202235&color=edb641&logo=python&logoColor=edb641)](https://pypi.org/project/rolabesti/) +[![Python Versions](https://img.shields.io/pypi/pyversions/rolabesti?labelColor=202235&color=edb641&logo=python&logoColor=edb641)](https://pypi.org/project/rolabesti/) +[![License - MIT](https://img.shields.io/badge/license-MIT-202235.svg?logo=python&labelColor=202235&color=edb641&logoColor=edb641)](https://spdx.org/licenses/) +[![Downloads](https://static.pepy.tech/badge/rolabesti)](https://pepy.tech/project/rolabesti) + +[![Typer](https://img.shields.io/badge/Typer-0.12.3-009485?style=for-the-badge&logo=fastapi&logoColor=white)](https://typer.tiangolo.com/) +[![Rich](https://img.shields.io/badge/rich-13.7.1-0094?style=for-the-badge&logo=rich&logoColor=white)](https://rich.readthedocs.io/en/latest/) +[![Pydantic](https://img.shields.io/badge/Pydantic-2.7.0-e92063?style=for-the-badge&logo=pydantic&logoColor=white)](https://docs.pydantic.dev/latest/) +[![Mutagen](https://img.shields.io/badge/mutagen-1.47.0-009758?style=for-the-badge&logo=mutagen&logoColor=red)](https://rich.readthedocs.io/en/latest/) + +- [Motivation](#motivation) +- [Description](#description) +- [Key Features](#key-features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Preparation](#preparation) +- [Examples](#examples) +- [Usage](#usage) + +## Motivation + +The main purpose of this app is to give a solution to the scenario that +some music fan, DJ, bartender, podcast enthusiast, or melomaniac may face: +"Having a great bunch of songs, what music do I play now?". For instance, +"what random songs of this artist or that genre can fill the next hour?" +is the question that **rolabesti** answers. + +## Description + +**rolabesti** is a CLI application to manage collections of mp3 tracks, +supporting these actions: loading metadata to database, parsing, +searching, listing, playing, enqueueing, copying, and tagging. + +## Key Features + +- Any audio file in mp3 format serves as raw material for the app. +- Select random and sorted songs matching multiple criteria. +- Play music directly in the terminal or send the tracklist to the default app. +- Tracks missing ID3 tags can be classified and leveraged. +- Mixer to avoid silence between songs. +- Selected tracklist length becomes a useful timer. +- OS independent. + +## Requirements + +- Python 3.10+. + +## Installation + +- The recommended way to install is using [pipx](https://pipx.pypa.io/stable/installation/#installing-pipx). + +```bash +pipx install rolabesti +``` + +## Preparation + +All mp3 files located at user's `Music` directory compose the music collection. +Optionally, folders can be labeled to apply any of the following patterns. +This way the database is better populated with the path fields and the accuracy +of the matching tracks improves. + +- `Artists//.mp3` +- `Artists/<artist>/<album>/[<side>/]<title>.mp3` +- `Albums/<album>/[<side>/]<title>.mp3` +- `Genres/<genre>/<title>.mp3` +- `Genres/<genre>/<artist>/<title>.mp3` +- `Genres/<genre>/<artist>/<album>/[<side>/]<title>.mp3` +- `Genres/<genre>/Albums/<album>/[<side>/]<title>.mp3` +- `Places/<place>/<title>.mp3` +- `Places/<place>/<artist>/<title>.mp3` +- `Places/<place>/<artist>/<album>/[<side>/]<title>.mp3` +- `Places/<place>/Albums/<album>/[<side>/]<title>.mp3` +- `Places/<place>/Genres/<genre>/<title>.mp3` +- `Places/<place>/Genres/<genre>/<artist>/<title>.mp3` +- `Places/<place>/Genres/<genre>/<artist>/<album>/[<side>/]<title>.mp3` +- `Places/<place>/Genres/<genre>/Albums/<album>/[<side>/]<title>.mp3` + +`<title>`, `<artist>`, `<album>`, `<side>` (optional), `<genre>`, and `<place>` are placeholders. + +The minimum steps to start playing are: + +```bash +rolabesti init +rolabesti play +``` + +Optionally, when the default app is selected as the player, `vlc` is recommended with this configuration: + +- Tools/Preferences/Interface/Playlist and Instances + - Allow only one instance: `checked` + - Enqueue items into playlist in one instance mode: `checked` + +## Examples + +To play two hours of rock music, limiting the track length to 5 +minutes, with random sorting: + +```bash +rolabesti play -l 120 -g rock --max 5 -s random +``` + +To play an hour of rap music from Iceland, skipping intro and outro +tracks (less than 2 minutes length), with ascending sorting: + +```bash +rolabesti play -l 60 -g rap -p Iceland --min 2 -s asc +``` + +## Usage + +**Usage**: + +```bash +rolabesti [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +* `--version`: Show the application version and exit. +* `--install-completion`: Install completion for the current shell. +* `--show-completion`: Show completion for the current shell, to copy it or customize the installation. +* `-h, --help`: Show this message and exit. + +**Commands**: + +* `config`: Manage configuration settings. +* `init`: Initialize database. +* `list`: List matching tracks. +* `play`: Play and enqueue matching tracks. +* `copy`: Copy matching tracks to a directory. +* `tag`: Update ID3 tags with path fields (file and database). + +## `rolabesti config` + +Manage configuration settings. + +**Usage**: + +```bash +rolabesti config [OPTIONS] +``` + +**Options**: + +* `--list`: List configuration settings. +* `--reset`: Reset configuration settings. +* `-h, --help`: Show this message and exit. + +**Main settings**: + +* `--max INTEGER RANGE [x>=0]`: Set default maximum track length in minutes (0 means disabled). +* `--min INTEGER RANGE [x>=0]`: Set default minimum track length in minutes. +* `-l, --length INTEGER RANGE [x>=0]`: Set default maximum tracklist length in minutes (0 means disabled). +* `-s, --sorting [asc|desc|random]`: Set default order by track path. + +**Play settings**: + +* `-o, --overlap-length INTEGER RANGE [0<=x<=30]`: Set default overlap length in seconds between two consecutive tracks (0 means disabled). + +**Database settings**: + +* `--music-directory DIRECTORY`: Set default path to mp3 files. + +**Copy settings**: + +* `--copy-directory DIRECTORY`: Set default path to destiny directory. + +## `rolabesti init` + +Initialize database. + +**Usage**: + +```bash +rolabesti init [OPTIONS] +``` + +**Options**: + +* `-d, --music-directory DIRECTORY`: Path to mp3 files. [default: /home/user/Music] +* `-h, --help`: Show this message and exit. + +## `rolabesti list` + +List matching tracks. + +**Usage**: + +```bash +rolabesti list [OPTIONS] +``` + +**Options**: + +* `-h, --help`: Show this message and exit. + +**Search filters**: + +* `-ar, --artist TEXT`: Track artist. +* `-t, --title TEXT`: Track title. +* `-al, --album TEXT`: Track album. +* `-g, --genre TEXT`: Track genre. +* `-p, --place TEXT`: Track place. +* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10] +* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0] + +**Tracklist selectors**: + +* `-s, --sorting [asc|desc|random]`: Order by track path. [default: random] + +## `rolabesti play` + +Play and enqueue matching tracks. + +**Usage**: + +```bash +rolabesti play [OPTIONS] +``` + +**Options**: + +* `--cli / --no-cli`: Select cli or default app. [default: cli] +* `-o, --overlap-length INTEGER RANGE [0<=x<=30]`: Overlap length in seconds between two consecutive tracks (only with --cli, 0 means disabled). [default: 3] +* `-h, --help`: Show this message and exit. + +**Search filters**: + +* `-ar, --artist TEXT`: Track artist. +* `-t, --title TEXT`: Track title. +* `-al, --album TEXT`: Track album. +* `-g, --genre TEXT`: Track genre. +* `-p, --place TEXT`: Track place. +* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10] +* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0] + +**Tracklist selectors**: + +* `-l, --length INTEGER RANGE [x>=0]`: Maximum tracklist length in minutes (0 means disabled). [default: 60] +* `-s, --sorting [asc|desc|random]`: Order by track path. [default: random] + +## `rolabesti copy` + +Copy matching tracks to a directory. + +**Usage**: + +```bash +rolabesti copy [OPTIONS] +``` + +**Options**: + +* `-d, --copy-directory DIRECTORY`: Path to destiny directory. [default: /home/user/Documents] +* `-h, --help`: Show this message and exit. + +**Search filters**: + +* `-ar, --artist TEXT`: Track artist. +* `-t, --title TEXT`: Track title. +* `-al, --album TEXT`: Track album. +* `-g, --genre TEXT`: Track genre. +* `-p, --place TEXT`: Track place. +* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10] +* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0] + +**Tracklist selectors**: + +* `-l, --length INTEGER RANGE [x>=0]`: Maximum tracklist length in minutes (0 means disabled). [default: 60] +* `-s, --sorting [asc|desc|random]`: Order by track path. [default: random] + +## `rolabesti tag` + +Update ID3 tags with path fields (file and database). + +**Usage**: + +```bash +rolabesti tag [OPTIONS] +``` + +**Options**: + +* `--id3-tag [artist|title|album|genre]`: ID3 tag to be updated. [required] +* `-h, --help`: Show this message and exit. + +**Search filters**: + +* `-ar, --artist TEXT`: Track artist. +* `-t, --title TEXT`: Track title. +* `-al, --album TEXT`: Track album. +* `-g, --genre TEXT`: Track genre. +* `-p, --place TEXT`: Track place. +* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10] +* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0] diff --git a/README.rst b/README.rst deleted file mode 100644 index 7a9b5ae..0000000 --- a/README.rst +++ /dev/null @@ -1,126 +0,0 @@ -rolabesti -========= - -.. image:: https://img.shields.io/pypi/v/rolabesti.svg - :target: https://pypi.org/project/rolabesti/ - -.. image:: https://img.shields.io/pypi/pyversions/rolabesti.svg - :target: https://pypi.org/project/rolabesti/ - -.. image:: https://img.shields.io/pypi/wheel/rolabesti.svg - :target: https://pypi.org/project/rolabesti/ - -.. image:: https://circleci.com/gh/kinuax/rolabesti.svg?style=shield - :target: https://circleci.com/gh/kinuax/rolabesti - -.. image:: https://img.shields.io/pypi/l/rolabesti.svg - :target: https://pypi.org/project/rolabesti/ - -- `Motivation <#motivation>`__ -- `Description <#description>`__ -- `Requirements <#requirements>`__ -- `Installation <#installation>`__ -- `Configuration <#configuration>`__ -- `Usage <#usage>`__ - -Motivation ----------- - -The main motivation is to solve the scenario where some music fan, DJ, bartender, or melomaniac may face: 'Considering these tons of mp3 files around, what music do I play?'. For instance, 'what genre would I want to listen?' and 'which random songs can fill up the available time that I have?' are the type of questions that **rolabesti** answers. - -Description ------------ - -**rolabesti** is a CLI application to manage a music library, performing the following actions on mp3 files: loading to database, parsing, searching, playing, enqueueing, copying, and tagging. - -Requirements ------------- - -- Linux platform. -- Python 3.10+. A virtual environment is highly recommended. -- MongoDB instance. -- vlc player. - -Installation ------------- - -.. code-block:: bash - - $ pip install rolabesti - -Configuration -------------- - -The default settings can be overriden in ``~/.config/rolabesti/rolabesti.conf``. This configuration file has INI syntax with a unique section named ``[rolabesti]``. - -- ``MUSIC_DIR``: path where the mp3 files are located, default is ``~/Music``. -- ``MAX_TRACK_LENGTH``: maximum track length in minutes, corresponding to the ``MAX`` argument, default is ``10``. -- ``MIN_TRACK_LENGTH``: minimum track length in minutes, corresponding to the ``MIN`` argument, default is ``0``. -- ``MAX_TRACKLIST_LENGTH``: maximum tracklist length in minutes, corresponding to the ``MAX_TRACKLIST_LENGTH`` argument - ``0`` denotes no tracklist length limit, default is ``60``. -- ``SORTING``: tracklist sorting by trackpath, corresponding to the ``SORTING`` argument - choices are ``asc`` (ascending), ``desc`` (descending) and ``random``, default is ``random``. -- ``PLAYER``: player to play and enqueue tracks, corresponding to the ``PLAYER`` argument - choices are ``shell`` (play tracks directly in the shell) and ``vlc`` (play tracks in the vlc player, opening it if necessary), default is ``vlc``. -- ``OVERLAP_LENGTH``: when selecting ``shell`` player, overlap length in seconds of two consecutive tracks, corresponding to the ``OVERLAP_LENGTH`` argument - minimum is ``0``, maximum is ``30``, default is ``3``. The overlap length determines the period where the last seconds of the previous track and the first seconds of the next track are playing simultaneously. -- ``MONGO_HOST``: MongoDB host, default is ``localhost``. -- ``MONGO_PORT``: MongoDB port, default is ``27017``. -- ``MONGO_DBNAME``: MongoDB database name, default is ``rolabesti``. -- ``MONGO_COLNAME``: MongoDB collection name, default is ``tracks``. - -Before running the application, locating the mp3 files in ``MUSIC_DIR`` is enough. Besides, the searching results become more accurate when the track path has one of following patterns. - -- ``MUSIC_DIR/Places/<place>/Genres/<genre>/Albums/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/Genres/<genre>/<artist>/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/Genres/<genre>/<artist>/<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/Genres/<genre>/`<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/Albums/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/<artist>/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/<artist>/<title>.mp3`` -- ``MUSIC_DIR/Places/<place>/<title>.mp3`` -- ``MUSIC_DIR/Genres/<genre>/Albums/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Genres/<genre>/<artist>/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Genres/<genre>/<artist>/<title>.mp3`` -- ``MUSIC_DIR/Genres/<genre>/<title>.mp3`` -- ``MUSIC_DIR/Artists/<artist>/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/Artists/<artist>/<title>.mp3`` -- ``MUSIC_DIR/Albums/<album>/[<side>/]<title>.mp3`` -- ``MUSIC_DIR/[some/path/]<title>.mp3`` - -``<place>``, ``<genre>``, ``<artist>``, ``<album>``, ``<side>`` and ``<title>`` are placeholders of any length and character. The square brackets denote optional. - -The database is loaded with tracks metadata running the ``load`` subcommand. - -.. code-block:: bash - - $ rolabesti load - -When selecting ``vlc`` player, unique running instance configuration is recommended. - -- Tools/Preferences/Interface/Playlist and Instances - - Allow only one instance: ``checked`` - - Enqueue items into playlist in one instance mode: ``checked`` - -Usage ------ - -.. code-block:: bash - - $ rolabesti [-h] SUBCOMMAND [ARGUMENTS] - -You can check the arguments for each subcommand with: - -.. code-block:: bash - - $ rolabesti SUBCOMMAND -h - -Let's see a couple of examples. - -To play two hours of rock music, limiting the track length to 10 minutes, with random sorting: - -.. code-block:: bash - - $ rolabesti play -g rock -l 120 --max 10 -s random - -To play an hour of rap music from Iceland, skipping intro and outro tracks (less than 2 minutes length), with ascending sorting: - -.. code-block:: bash - - $ rolabesti play -g rap -l 60 -p Iceland --min 2 -s asc