# CPlayer
**C**ommand Line **P**ython p**layer** is a minimalist song player written with Python
([github](https://github.com/eccanto/cplayer)), this application offers a wide range of functionality to
enhance your music listening, playlist management, filtering and searching songs and more using keyboard shortcuts.
Below, you'll find a comprehensive list of keyboard shortcuts and their corresponding actions within the application,
and additional configurations: [keyboard shortcuts and customized configurations](cplayer/documentation/help.md).
Only tested in Linux.
## Table of contents
* [Features](#features)
* [Get started](#get-started)
* [Installation](#installation)
* [Uninstallation](#uninstallation)
* [Usage](#usage)
* [Options](#options)
* [TODO](#todo)
* [Known issues](#known-issues)
* [Reports and Debugging](#reports-and-debugging)
* [Developers](#developers)
* [Dependencies](#dependencies)
* [Set up pre-commit](#set-up-pre-commit)
* [Basic configuration](#basic-configuration)
* [Testing](#testing)
* [Advanced configuration](#advanced-configuration)
* [Static code analysis tools](#static-code-analysis-tools)
* [Python static checkers](#python-static-checkers)
* [Run manually](#run-manually)
* [License](#license)
* [Changelog](#changelog)
## Features
* GUI customization.
* If your system does not support the icons used you can set them manually in [~/.config/cplayer/config.yaml](cplayer/resources/config/default.yaml).
* Keyboard shortcuts customization.
* Create multiple playlists and manage then.
* Multiple ways to navigate through the playlist including jumping by position, filtering, manual displacements,
sorting, etc.
* Download song from a YouTube URL (`--url`).
## Get started
### Installation
This application can be simply installed by running:
```bash
pip install cplayer
```
if you want to install from a source distribution:
```bash
git clone https://github.com/eccanto/cplayer
cd cplayer/
pip install .
```
### Uninstallation
To uninstall the application you can use `pip`:
```bash
pip uninstall cplayer
```
### Usage
To run the application you must run the command line:
```bash
cplayer
```
By default the application will load the last playlist if it exists, otherwise the application will use the current
path to load the `.mp3` and `.wav` files from the directory (not recursively).
### Options
```
$ cplayer --help
Usage: cplayer [OPTIONS]
Command Line Python player CLI.
This command line tool plays music files from a specified directory or last
used playlist.
Examples:
- Play music from the current directory or the last used playlist if it
exists:
$ cplayer
- Play music from a specific directory:
$ cplayer --path /path/to/music_directory
- Download song from YouTube
$ cplayer --url 'https://www.youtube.com/watch?v=xyz'
For more information, visit https://github.com/eccanto/cplayer
Options:
-p, --path PATH Path to the directory containing your music files.
-u, --url TEXT URL of the song to download from YouTube.
--version Show the version and exit.
--help Show this message and exit.
```
### TODO
* Add favorites feature.
* Add option to restore default configurations.
* Add confirmation dialog to remove/add songs.
* Add "recent" sections: recent folders, recent playlists, recent songs.
### Known issues
* `tmux` subpanels may cause the application dimensions to be incorrect.
### Reports and Debugging
The application uses a log file located at `~/.cplayer/logfile.log` to report and debug errors. The log file contains
detailed information about all errors that occur while the application is running, including the time and date of the
error, the error message, and the stack trace.
To view the log file, you can use a text editor or a terminal emulator, e.g.:
```bash
tail -f ~/.cplayer/logfile.log
```
The log file can be used to report and debug errors.
### Developers
This project use [tox](https://tox.wiki/en/latest/) and [pytest](https://docs.pytest.org/) to run the library tests.
#### Dependencies
To use development tools you must install the poetry packages:
```bash
poetry install --with dev
```
#### Set up pre-commit
After cloning the repository run the following command in the repository root, this ensures that library tests are run
before each commit into the repository to maintain the quality of the project:
```bash
git config core.hooksPath .githooks
```
#### Basic configuration
Install development python requirements
```bash
poetry install
```
#### Testing
Simply run "`tox`" to execute all the library tests.
```bash
poetry run tox
```
To run the tests for a particular Python version, you can do:
```bash
poetry run tox -e py38
```
To clean the test environment:
```bash
poetry run tox -e clean
```
To publish the pypi package:
```bash
poetry run tox -e publish
```
#### Advanced configuration
By default `tox` will look for the python versions available on the system, and will run the compatibility tests on
the detected ones, and skip the versions not found. To ensure that compatibility tests are run for all Python
versions, the following steps must be followed:
1. Install [pyenv](https://github.com/pyenv/pyenv)
2. Install python versions:
```bash
for python_version in "3.10" "3.11" "3.12"; do pyenv install ${python_version}; done
```
3. Enable python versions:
```bash
pyenv local "3.10" "3.11" "3.12"
```
#### Static code analysis tools
These are the static code analysis tools that will help us to follow good practices and style guides of our source code.
We will be using the following tools, which will be executed when generating a new push in the repository (git hooks).
### Python static code analysis tools
The tools used are:
* [ruff](https://github.com/astral-sh/ruff): An extremely fast Python linter and code formatter, written in Rust.
Tools executed by Ruff:
* [pycodestyle](https://github.com/PyCQA/pycodestyle): Pycodestyle is a tool to check your Python code against some
of the style conventions in [PEP 8](https://peps.python.org/pep-0008/).
* [ruff-format](https://github.com/astral-sh/ruff/blob/main/docs/formatter.md#black-compatibility): The formatter
is designed to be a drop-in replacement for [Black](https://github.com/psf/black).
* [flake8](https://github.com/PyCQA/flake8): Flake8 is a python tool that glues together pycodestyle, pyflakes,
and third-party plugins to check the style and quality of some python code.
* [pydocstyle](https://github.com/PyCQA/pydocstyle): Pydocstyle is a static analysis tool for checking compliance
with [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
* [isort](https://pycqa.github.io/isort/): Python utility / library to sort imports alphabetically, and automatically
separated into sections and by type.
* [mccabe](https://github.com/PyCQA/mccabe): Complexity checker.
* [bandit](https://github.com/PyCQA/bandit): Bandit is a tool designed to find common security issues.
* [tryceratops](https://github.com/guilatrova/tryceratops): A linter to prevent exception handling antipatterns in
Python.
* [prospector](https://github.com/PyCQA/prospector): Prospector is a tool to analyze Python code and output information
about errors, potential problems, convention violations and complexity.
Tools executed by Prospector:
* [pylint](https://github.com/PyCQA/pylint): Pylint is a Python static code analysis tool which looks for programming
errors, helps enforcing a coding standard, sniffs for code smells and offers simple refactoring suggestions.
* [dodgy](https://github.com/landscapeio/dodgy): It is a series of simple regular expressions designed to detect
things such as accidental SCM diff checkins, or passwords or secret keys hard coded into files.
* [mypy](https://github.com/python/mypy): Mypy is an optional static type checker for Python.
* [pyroma](https://github.com/regebro/pyroma): Pyroma is a product aimed at giving a rating of how well a Python
project complies with the best practices of the Python packaging ecosystem, primarily PyPI, pip, Distribute etc,
as well as a list of issues that could be improved.
* [detect-secrets](https://github.com/Yelp/detect-secrets): Detect secrets in your code.
### Run manually
```bash
poetry run tox -e check_code
```
## License
[MIT](./LICENSE)
## Changelog
* 1.0.0 - Initial version.
* 1.0.1:
* `refactor`: Updates documentation.
* `fix`: Default playlist loading.
* `feat`: Adds `--version` command line argument.
* 1.0.2:
* `feat`: Download song from a YouTube URL (`--url`).
* 1.1.0:
* `fix`: Updates the application when a song is broken.
* `feat`: Adds log details when downloading a song.
* 1.1.1:
* `fix`: Stores absolute paths of the songs in the playlist file.
* `refactor`: Changes keyboard shortcuts (`vim` style).
* 1.1.2:
* `fix`: Handle error when song files are not found.
* `documentation`: Adds development documentation.
* `refactor`: Enables log file.
* 1.1.3:
* `refactor`: Updates requirements compatibility.
* 1.1.4:
* `refactor`: Updates application compatibility.
* 1.1.5:
* `fix`: Apply background and primary color from local configuration file.
* 1.2.0:
* `feat`: Adds displacement to the last position with `:$`.
* `feat`: Adds synchronization feature to take a directory path and synchronize its files with the current playlist,
if the directory contains previously deleted songs they are not re-added.
* 1.2.1:
* `feat`: Adds compatibility to python 3.10 and 3.12.
* `fix`: Fixes an error in the size of the layouts.
* `refactor`: Adds poetry as a dependency and packaging manager.
* `refactor`: General refactoring on static code analysis tools.
* 1.3.0:
* `feat`: Adds support for wav song files.
* `documentation`: Refactor developers documentation.
* 1.3.1:
* `fix`: Adds file explorer quit action.
* `refactor`: Update textual package.
Raw data
{
"_id": null,
"home_page": "https://github.com/eccanto/cplayer",
"name": "cplayer",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "music, songs player, command line",
"author": "Erik Ccanto",
"author_email": "ccanto.erik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/15/15/33e60074f0635c9a273cd8accd09ff85a40cbab518bdaf56fa8a112006b9/cplayer-1.3.1.tar.gz",
"platform": null,
"description": "# CPlayer\n\n\n\n\n\n\n\n\n**C**ommand Line **P**ython p**layer** is a minimalist song player written with Python\n([github](https://github.com/eccanto/cplayer)), this application offers a wide range of functionality to\nenhance your music listening, playlist management, filtering and searching songs and more using keyboard shortcuts.\n\nBelow, you'll find a comprehensive list of keyboard shortcuts and their corresponding actions within the application,\nand additional configurations: [keyboard shortcuts and customized configurations](cplayer/documentation/help.md).\n\nOnly tested in Linux.\n\n## Table of contents\n\n* [Features](#features)\n* [Get started](#get-started)\n * [Installation](#installation)\n * [Uninstallation](#uninstallation)\n * [Usage](#usage)\n * [Options](#options)\n* [TODO](#todo)\n* [Known issues](#known-issues)\n* [Reports and Debugging](#reports-and-debugging)\n* [Developers](#developers)\n * [Dependencies](#dependencies)\n * [Set up pre-commit](#set-up-pre-commit)\n * [Basic configuration](#basic-configuration)\n * [Testing](#testing)\n * [Advanced configuration](#advanced-configuration)\n * [Static code analysis tools](#static-code-analysis-tools)\n * [Python static checkers](#python-static-checkers)\n * [Run manually](#run-manually)\n* [License](#license)\n* [Changelog](#changelog)\n\n## Features\n\n* GUI customization.\n * If your system does not support the icons used you can set them manually in [~/.config/cplayer/config.yaml](cplayer/resources/config/default.yaml).\n* Keyboard shortcuts customization.\n* Create multiple playlists and manage then.\n* Multiple ways to navigate through the playlist including jumping by position, filtering, manual displacements,\n sorting, etc.\n* Download song from a YouTube URL (`--url`).\n\n## Get started\n\n### Installation\n\nThis application can be simply installed by running:\n\n```bash\npip install cplayer\n```\n\nif you want to install from a source distribution:\n\n```bash\ngit clone https://github.com/eccanto/cplayer\ncd cplayer/\npip install .\n```\n\n### Uninstallation\n\nTo uninstall the application you can use `pip`:\n\n```bash\npip uninstall cplayer\n```\n\n### Usage\n\nTo run the application you must run the command line:\n\n```bash\ncplayer\n```\n\nBy default the application will load the last playlist if it exists, otherwise the application will use the current\npath to load the `.mp3` and `.wav` files from the directory (not recursively).\n\n### Options\n\n```\n$ cplayer --help\n\nUsage: cplayer [OPTIONS]\n\n Command Line Python player CLI.\n\n This command line tool plays music files from a specified directory or last\n used playlist.\n\n Examples:\n\n - Play music from the current directory or the last used playlist if it\n exists:\n\n $ cplayer\n\n - Play music from a specific directory:\n\n $ cplayer --path /path/to/music_directory\n\n - Download song from YouTube\n\n $ cplayer --url 'https://www.youtube.com/watch?v=xyz'\n\n For more information, visit https://github.com/eccanto/cplayer\n\nOptions:\n -p, --path PATH Path to the directory containing your music files.\n -u, --url TEXT URL of the song to download from YouTube.\n --version Show the version and exit.\n --help Show this message and exit.\n```\n\n### TODO\n\n* Add favorites feature.\n* Add option to restore default configurations.\n* Add confirmation dialog to remove/add songs.\n* Add \"recent\" sections: recent folders, recent playlists, recent songs.\n\n### Known issues\n\n* `tmux` subpanels may cause the application dimensions to be incorrect.\n\n### Reports and Debugging\n\nThe application uses a log file located at `~/.cplayer/logfile.log` to report and debug errors. The log file contains\ndetailed information about all errors that occur while the application is running, including the time and date of the\nerror, the error message, and the stack trace.\n\nTo view the log file, you can use a text editor or a terminal emulator, e.g.:\n\n```bash\ntail -f ~/.cplayer/logfile.log\n```\n\nThe log file can be used to report and debug errors.\n\n### Developers\n\nThis project use [tox](https://tox.wiki/en/latest/) and [pytest](https://docs.pytest.org/) to run the library tests.\n\n#### Dependencies\n\nTo use development tools you must install the poetry packages:\n\n```bash\npoetry install --with dev\n```\n\n#### Set up pre-commit\n\nAfter cloning the repository run the following command in the repository root, this ensures that library tests are run\nbefore each commit into the repository to maintain the quality of the project:\n\n```bash\ngit config core.hooksPath .githooks\n```\n\n#### Basic configuration\n\nInstall development python requirements\n\n```bash\npoetry install\n```\n\n#### Testing\n\nSimply run \"`tox`\" to execute all the library tests.\n\n```bash\npoetry run tox\n```\n\nTo run the tests for a particular Python version, you can do:\n\n\n```bash\npoetry run tox -e py38\n```\n\nTo clean the test environment:\n\n```bash\npoetry run tox -e clean\n```\n\nTo publish the pypi package:\n\n```bash\npoetry run tox -e publish\n```\n\n#### Advanced configuration\n\nBy default `tox` will look for the python versions available on the system, and will run the compatibility tests on\nthe detected ones, and skip the versions not found. To ensure that compatibility tests are run for all Python\nversions, the following steps must be followed:\n\n1. Install [pyenv](https://github.com/pyenv/pyenv)\n2. Install python versions:\n\n ```bash\n for python_version in \"3.10\" \"3.11\" \"3.12\"; do pyenv install ${python_version}; done\n ```\n\n3. Enable python versions:\n\n ```bash\n pyenv local \"3.10\" \"3.11\" \"3.12\"\n ```\n\n#### Static code analysis tools\n\nThese are the static code analysis tools that will help us to follow good practices and style guides of our source code.\nWe will be using the following tools, which will be executed when generating a new push in the repository (git hooks).\n\n### Python static code analysis tools\n\nThe tools used are:\n\n* [ruff](https://github.com/astral-sh/ruff): An extremely fast Python linter and code formatter, written in Rust.\n\n Tools executed by Ruff:\n\n * [pycodestyle](https://github.com/PyCQA/pycodestyle): Pycodestyle is a tool to check your Python code against some\n of the style conventions in [PEP 8](https://peps.python.org/pep-0008/).\n * [ruff-format](https://github.com/astral-sh/ruff/blob/main/docs/formatter.md#black-compatibility): The formatter\n is designed to be a drop-in replacement for [Black](https://github.com/psf/black).\n * [flake8](https://github.com/PyCQA/flake8): Flake8 is a python tool that glues together pycodestyle, pyflakes,\n and third-party plugins to check the style and quality of some python code.\n * [pydocstyle](https://github.com/PyCQA/pydocstyle): Pydocstyle is a static analysis tool for checking compliance\n with [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).\n * [isort](https://pycqa.github.io/isort/): Python utility / library to sort imports alphabetically, and automatically\n separated into sections and by type.\n * [mccabe](https://github.com/PyCQA/mccabe): Complexity checker.\n * [bandit](https://github.com/PyCQA/bandit): Bandit is a tool designed to find common security issues.\n * [tryceratops](https://github.com/guilatrova/tryceratops): A linter to prevent exception handling antipatterns in\n Python.\n\n* [prospector](https://github.com/PyCQA/prospector): Prospector is a tool to analyze Python code and output information\n about errors, potential problems, convention violations and complexity.\n\n Tools executed by Prospector:\n * [pylint](https://github.com/PyCQA/pylint): Pylint is a Python static code analysis tool which looks for programming\n errors, helps enforcing a coding standard, sniffs for code smells and offers simple refactoring suggestions.\n * [dodgy](https://github.com/landscapeio/dodgy): It is a series of simple regular expressions designed to detect\n things such as accidental SCM diff checkins, or passwords or secret keys hard coded into files.\n * [mypy](https://github.com/python/mypy): Mypy is an optional static type checker for Python.\n * [pyroma](https://github.com/regebro/pyroma): Pyroma is a product aimed at giving a rating of how well a Python\n project complies with the best practices of the Python packaging ecosystem, primarily PyPI, pip, Distribute etc,\n as well as a list of issues that could be improved.\n\n* [detect-secrets](https://github.com/Yelp/detect-secrets): Detect secrets in your code.\n\n### Run manually\n\n```bash\npoetry run tox -e check_code\n```\n\n## License\n\n[MIT](./LICENSE)\n\n## Changelog\n\n* 1.0.0 - Initial version.\n* 1.0.1:\n * `refactor`: Updates documentation.\n * `fix`: Default playlist loading.\n * `feat`: Adds `--version` command line argument.\n* 1.0.2:\n * `feat`: Download song from a YouTube URL (`--url`).\n* 1.1.0:\n * `fix`: Updates the application when a song is broken.\n * `feat`: Adds log details when downloading a song.\n* 1.1.1:\n * `fix`: Stores absolute paths of the songs in the playlist file.\n * `refactor`: Changes keyboard shortcuts (`vim` style).\n* 1.1.2:\n * `fix`: Handle error when song files are not found.\n * `documentation`: Adds development documentation.\n * `refactor`: Enables log file.\n* 1.1.3:\n * `refactor`: Updates requirements compatibility.\n* 1.1.4:\n * `refactor`: Updates application compatibility.\n* 1.1.5:\n * `fix`: Apply background and primary color from local configuration file.\n* 1.2.0:\n * `feat`: Adds displacement to the last position with `:$`.\n * `feat`: Adds synchronization feature to take a directory path and synchronize its files with the current playlist,\n if the directory contains previously deleted songs they are not re-added.\n* 1.2.1:\n * `feat`: Adds compatibility to python 3.10 and 3.12.\n * `fix`: Fixes an error in the size of the layouts.\n * `refactor`: Adds poetry as a dependency and packaging manager.\n * `refactor`: General refactoring on static code analysis tools.\n* 1.3.0:\n * `feat`: Adds support for wav song files.\n * `documentation`: Refactor developers documentation.\n* 1.3.1:\n * `fix`: Adds file explorer quit action.\n * `refactor`: Update textual package.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Minimalist song player implemented with Python",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/eccanto/cplayer",
"Repository": "https://github.com/eccanto/cplayer"
},
"split_keywords": [
"music",
" songs player",
" command line"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c99afb1061df192f5fe76de84178b5c700415ab5e272509616a07f3a0b3241c",
"md5": "e1ce376008bdb004cf34587867e85d20",
"sha256": "f7b111e335f3bd6e3c28b912b3a97052321ef23f9bed05d15e52931240502cff"
},
"downloads": -1,
"filename": "cplayer-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1ce376008bdb004cf34587867e85d20",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 37225,
"upload_time": "2024-04-27T14:24:46",
"upload_time_iso_8601": "2024-04-27T14:24:46.613880Z",
"url": "https://files.pythonhosted.org/packages/5c/99/afb1061df192f5fe76de84178b5c700415ab5e272509616a07f3a0b3241c/cplayer-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "151533e60074f0635c9a273cd8accd09ff85a40cbab518bdaf56fa8a112006b9",
"md5": "95e16ec3b250b01485f2be316149ac53",
"sha256": "8bf1e62d88c8f03b455d427cac23f2015ddcc1a559f9159ca9d734e547e259c2"
},
"downloads": -1,
"filename": "cplayer-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "95e16ec3b250b01485f2be316149ac53",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 27568,
"upload_time": "2024-04-27T14:24:48",
"upload_time_iso_8601": "2024-04-27T14:24:48.882774Z",
"url": "https://files.pythonhosted.org/packages/15/15/33e60074f0635c9a273cd8accd09ff85a40cbab518bdaf56fa8a112006b9/cplayer-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 14:24:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eccanto",
"github_project": "cplayer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "cplayer"
}
JSON
