# rolabesti - CLI app to manage, search, and play collections of mp3 tracks.
[](https://pypi.org/project/rolabesti/)
[](https://pypi.org/project/rolabesti/)
[](https://spdx.org/licenses/)
[](https://pepy.tech/project/rolabesti)
[](https://typer.tiangolo.com/)
[](https://rich.readthedocs.io/en/latest/)
[](https://docs.pydantic.dev/latest/)
[](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/<artist>/<title>.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]
Raw data
{
"_id": null,
"home_page": "https://github.com/kinuax/rolabesti",
"name": "rolabesti",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "audio, sound, music, mp3, player, id3, cli, shell, terminal, typer, click, tinydb, vlc",
"author": "Kinuax",
"author_email": "kinuax@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/a7/80/b21892503ce3b98c192c03cb0805aa0ce0082b6044ae4bd7a1b73e25d07c/rolabesti-0.6.0.tar.gz",
"platform": null,
"description": "# rolabesti - CLI app to manage, search, and play collections of mp3 tracks.\n\n[](https://pypi.org/project/rolabesti/)\n[](https://pypi.org/project/rolabesti/)\n[](https://spdx.org/licenses/)\n[](https://pepy.tech/project/rolabesti)\n\n[](https://typer.tiangolo.com/)\n[](https://rich.readthedocs.io/en/latest/)\n[](https://docs.pydantic.dev/latest/)\n[](https://rich.readthedocs.io/en/latest/)\n\n- [Motivation](#motivation)\n- [Description](#description)\n- [Key Features](#key-features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Preparation](#preparation)\n- [Examples](#examples)\n- [Usage](#usage)\n\n## Motivation\n\nThe main purpose of this app is to give a solution to the scenario that\nsome music fan, DJ, bartender, podcast enthusiast, or melomaniac may face:\n\"Having a great bunch of songs, what music do I play now?\". For instance,\n\"what random songs of this artist or that genre can fill the next hour?\"\nis the question that **rolabesti** answers.\n\n## Description\n\n**rolabesti** is a CLI application to manage collections of mp3 tracks,\nsupporting these actions: loading metadata to database, parsing,\nsearching, listing, playing, enqueueing, copying, and tagging.\n\n## Key Features\n\n- Any audio file in mp3 format serves as raw material for the app. \n- Select random and sorted songs matching multiple criteria.\n- Play music directly in the terminal or send the tracklist to the default app.\n- Tracks missing ID3 tags can be classified and leveraged.\n- Mixer to avoid silence between songs.\n- Selected tracklist length becomes a useful timer. \n- OS independent.\n\n## Requirements\n\n- Python 3.10+.\n\n## Installation\n\n- The recommended way to install is using [pipx](https://pipx.pypa.io/stable/installation/#installing-pipx). \n\n```bash\npipx install rolabesti\n```\n\n## Preparation\n\nAll mp3 files located at user's `Music` directory compose the music collection.\nOptionally, folders can be labeled to apply any of the following patterns.\nThis way the database is better populated with the path fields and the accuracy\nof the matching tracks improves.\n\n- `Artists/<artist>/<title>.mp3`\n- `Artists/<artist>/<album>/[<side>/]<title>.mp3`\n- `Albums/<album>/[<side>/]<title>.mp3`\n- `Genres/<genre>/<title>.mp3`\n- `Genres/<genre>/<artist>/<title>.mp3`\n- `Genres/<genre>/<artist>/<album>/[<side>/]<title>.mp3`\n- `Genres/<genre>/Albums/<album>/[<side>/]<title>.mp3`\n- `Places/<place>/<title>.mp3`\n- `Places/<place>/<artist>/<title>.mp3`\n- `Places/<place>/<artist>/<album>/[<side>/]<title>.mp3`\n- `Places/<place>/Albums/<album>/[<side>/]<title>.mp3`\n- `Places/<place>/Genres/<genre>/<title>.mp3`\n- `Places/<place>/Genres/<genre>/<artist>/<title>.mp3`\n- `Places/<place>/Genres/<genre>/<artist>/<album>/[<side>/]<title>.mp3`\n- `Places/<place>/Genres/<genre>/Albums/<album>/[<side>/]<title>.mp3`\n\n`<title>`, `<artist>`, `<album>`, `<side>` (optional), `<genre>`, and `<place>` are placeholders.\n\nThe minimum steps to start playing are:\n\n```bash\nrolabesti init\nrolabesti play\n```\n\nOptionally, when the default app is selected as the player, `vlc` is recommended with this configuration:\n\n- Tools/Preferences/Interface/Playlist and Instances\n - Allow only one instance: `checked`\n - Enqueue items into playlist in one instance mode: `checked`\n\n## Examples\n\nTo play two hours of rock music, limiting the track length to 5\nminutes, with random sorting:\n\n```bash\nrolabesti play -l 120 -g rock --max 5 -s random\n```\n\nTo play an hour of rap music from Iceland, skipping intro and outro\ntracks (less than 2 minutes length), with ascending sorting:\n\n```bash\nrolabesti play -l 60 -g rap -p Iceland --min 2 -s asc\n```\n\n## Usage\n\n**Usage**:\n\n```bash\nrolabesti [OPTIONS] COMMAND [ARGS]...\n```\n\n**Options**:\n\n* `--version`: Show the application version and exit.\n* `--install-completion`: Install completion for the current shell.\n* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.\n* `-h, --help`: Show this message and exit.\n\n**Commands**:\n\n* `config`: Manage configuration settings.\n* `init`: Initialize database.\n* `list`: List matching tracks.\n* `play`: Play and enqueue matching tracks.\n* `copy`: Copy matching tracks to a directory.\n* `tag`: Update ID3 tags with path fields (file and database).\n\n## `rolabesti config`\n\nManage configuration settings.\n\n**Usage**:\n\n```bash\nrolabesti config [OPTIONS]\n```\n\n**Options**:\n\n* `--list`: List configuration settings.\n* `--reset`: Reset configuration settings.\n* `-h, --help`: Show this message and exit.\n\n**Main settings**:\n\n* `--max INTEGER RANGE [x>=0]`: Set default maximum track length in minutes (0 means disabled).\n* `--min INTEGER RANGE [x>=0]`: Set default minimum track length in minutes.\n* `-l, --length INTEGER RANGE [x>=0]`: Set default maximum tracklist length in minutes (0 means disabled).\n* `-s, --sorting [asc|desc|random]`: Set default order by track path.\n\n**Play settings**:\n\n* `-o, --overlap-length INTEGER RANGE [0<=x<=30]`: Set default overlap length in seconds between two consecutive tracks (0 means disabled).\n\n**Database settings**:\n\n* `--music-directory DIRECTORY`: Set default path to mp3 files.\n\n**Copy settings**:\n\n* `--copy-directory DIRECTORY`: Set default path to destiny directory.\n\n## `rolabesti init`\n\nInitialize database.\n\n**Usage**:\n\n```bash\nrolabesti init [OPTIONS]\n```\n\n**Options**:\n\n* `-d, --music-directory DIRECTORY`: Path to mp3 files. [default: /home/user/Music]\n* `-h, --help`: Show this message and exit.\n\n## `rolabesti list`\n\nList matching tracks.\n\n**Usage**:\n\n```bash\nrolabesti list [OPTIONS]\n```\n\n**Options**:\n\n* `-h, --help`: Show this message and exit.\n\n**Search filters**:\n\n* `-ar, --artist TEXT`: Track artist.\n* `-t, --title TEXT`: Track title.\n* `-al, --album TEXT`: Track album.\n* `-g, --genre TEXT`: Track genre.\n* `-p, --place TEXT`: Track place.\n* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10]\n* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0]\n\n**Tracklist selectors**:\n\n* `-s, --sorting [asc|desc|random]`: Order by track path. [default: random]\n\n## `rolabesti play`\n\nPlay and enqueue matching tracks.\n\n**Usage**:\n\n```bash\nrolabesti play [OPTIONS]\n```\n\n**Options**:\n\n* `--cli / --no-cli`: Select cli or default app. [default: cli]\n* `-o, --overlap-length INTEGER RANGE [0<=x<=30]`: Overlap length in seconds between two consecutive tracks (only with --cli, 0 means disabled). [default: 3]\n* `-h, --help`: Show this message and exit.\n\n**Search filters**:\n \n* `-ar, --artist TEXT`: Track artist.\n* `-t, --title TEXT`: Track title.\n* `-al, --album TEXT`: Track album.\n* `-g, --genre TEXT`: Track genre.\n* `-p, --place TEXT`: Track place.\n* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10]\n* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0]\n\n**Tracklist selectors**:\n\n* `-l, --length INTEGER RANGE [x>=0]`: Maximum tracklist length in minutes (0 means disabled). [default: 60]\n* `-s, --sorting [asc|desc|random]`: Order by track path. [default: random]\n\n## `rolabesti copy`\n\nCopy matching tracks to a directory.\n\n**Usage**:\n\n```bash\nrolabesti copy [OPTIONS]\n```\n\n**Options**:\n\n* `-d, --copy-directory DIRECTORY`: Path to destiny directory. [default: /home/user/Documents]\n* `-h, --help`: Show this message and exit.\n\n**Search filters**:\n\n* `-ar, --artist TEXT`: Track artist.\n* `-t, --title TEXT`: Track title.\n* `-al, --album TEXT`: Track album.\n* `-g, --genre TEXT`: Track genre.\n* `-p, --place TEXT`: Track place.\n* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10]\n* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0]\n\n**Tracklist selectors**:\n\n* `-l, --length INTEGER RANGE [x>=0]`: Maximum tracklist length in minutes (0 means disabled). [default: 60]\n* `-s, --sorting [asc|desc|random]`: Order by track path. [default: random]\n\n## `rolabesti tag`\n\nUpdate ID3 tags with path fields (file and database).\n\n**Usage**:\n\n```bash\nrolabesti tag [OPTIONS]\n```\n\n**Options**:\n\n* `--id3-tag [artist|title|album|genre]`: ID3 tag to be updated. [required]\n* `-h, --help`: Show this message and exit.\n\n**Search filters**:\n\n* `-ar, --artist TEXT`: Track artist.\n* `-t, --title TEXT`: Track title.\n* `-al, --album TEXT`: Track album.\n* `-g, --genre TEXT`: Track genre.\n* `-p, --place TEXT`: Track place.\n* `--max INTEGER RANGE [x>=0]`: Maximum track length in minutes (0 means disabled). [default: 10]\n* `--min INTEGER RANGE [x>=0]`: Minimum track length in minutes. [default: 0]\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI app to manage, search, and play collections of mp3 tracks.",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://github.com/kinuax/rolabesti",
"Homepage": "https://github.com/kinuax/rolabesti",
"Repository": "https://github.com/kinuax/rolabesti"
},
"split_keywords": [
"audio",
" sound",
" music",
" mp3",
" player",
" id3",
" cli",
" shell",
" terminal",
" typer",
" click",
" tinydb",
" vlc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "37822a78ce37bc102a5a2009dc7cd2521397716801a06278ca03003ee72bb59d",
"md5": "96e3458ef507895d61a30fa5f6212e50",
"sha256": "88e8cf2dec1939dfff68b132ca09fe08f749952d639d191a49ce904c0c14b82b"
},
"downloads": -1,
"filename": "rolabesti-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96e3458ef507895d61a30fa5f6212e50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 27033,
"upload_time": "2024-05-12T07:32:04",
"upload_time_iso_8601": "2024-05-12T07:32:04.931485Z",
"url": "https://files.pythonhosted.org/packages/37/82/2a78ce37bc102a5a2009dc7cd2521397716801a06278ca03003ee72bb59d/rolabesti-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a780b21892503ce3b98c192c03cb0805aa0ce0082b6044ae4bd7a1b73e25d07c",
"md5": "36a678600fadea0aabd1762220175960",
"sha256": "b6aa76c6f946b9fbcd167b9656447fae5e7c5d542ba44610931d2709eac81826"
},
"downloads": -1,
"filename": "rolabesti-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "36a678600fadea0aabd1762220175960",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 18499,
"upload_time": "2024-05-12T07:32:07",
"upload_time_iso_8601": "2024-05-12T07:32:07.054201Z",
"url": "https://files.pythonhosted.org/packages/a7/80/b21892503ce3b98c192c03cb0805aa0ce0082b6044ae4bd7a1b73e25d07c/rolabesti-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-12 07:32:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kinuax",
"github_project": "rolabesti",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "rolabesti"
}
JSON
