**<h1 align="center">Ethos</h1>**
<p align="center">
<img src="src/img/ethos_logo.jpg" alt="Logo of Ethos" width="300", height="300">
</p>
<div align="center">
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/Itz-Agasta/ethos/pulls)
[](https://codecov.io/gh/Itz-Agasta/ethos)
[](https://pypi.org/project/ethos/)
[](https://github.com/Itz-Agasta/ethos/issues)
[](https://github.com/Itz-Agasta/ethos/stargazers)
[](https://github.com/Itz-Agasta/ethos/commits/main)
</div>
<p align="center">
A modern, resource-efficient CLI music player that seamlessly integrates local music libraries with online streaming services. Experience high-quality audio playback, Spotify playlist synchronization, and an intuitive terminal interface designed for both developers and music enthusiasts.
<br />
<br />
<a href="https://www.youtube.com/watch?v=E1AjSHxe5NU&feature=youtu.be">View Demo</a>
·
<a href="https://github.com/Itz-Agasta/ethos/issues">Report Bug</a>
·
<a href="https://github.com/Itz-Agasta/ethos/issues">Request Feature</a>
·
<a href="https://github.com/Itz-Agasta/ethos/pulls">Send a Pull Request</a>
</p>
</p>
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Preview](#preview)
- [Technologies Used](#technologies-used)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [For Development:](#for-development)
- [For Distribution:](#for-distribution)
- [Usage:](#usage)
- [Basic Commands](#basic-commands)
- [Queue Management](#queue-management)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Basic Workflow](#basic-workflow)
- [Troubleshooting](#troubleshooting)
- [Common Issues](#common-issues)
- [Repository Structure](#repository-structure)
- [Contributors](#contributors)
- [License](#license)
## Features
🎵 **Universal Accessibility**
- High-quality terminal music playback accessible to both developers and general users
- Modern and feature-rich interface in your terminal
- Support for multiple audio formats (MP3, FLAC, WAV, AAC)
💻 **Resource Efficient**
- Lightweight application with minimal system resource consumption
- Can be used in devices like Raspberry Pi
- Optimized for lower-end devices without compromising functionality
🔄 **Unified Music Experience**
- Seamlessly bridges local music libraries with online streaming services
- All your music needs handled from a single terminal interface
- Import and sync your Spotify playlists
- Offline playback for downloaded tracks
⚡ **Developer-Centric**
- Terminal-native music solution that integrates with your development workflow
- Enhances productivity by keeping you in your preferred environment
## Preview
<p align="center">
<img src="src/img/ethos_ui.jpg" alt="Logo of Ethos">
</p>
## Technologies Used
- **Backend:** yt-dlp, python-vlc, spotify API, spotipy
- **Frontend:** Rich, Textual
- **Language:** Python
## Prerequisites
Make sure you have the following installed:
- Python 3.8 or later
- pip (Python package installer)
- VLC media player
## Quick Start
```bash
# Install Ethos
pip install ethos
# Start playing music
ethos
```
## Installation
### For Development:
1. **Clone the Repository:**
```bash
git clone https://github.com//Itz-Agasta/ethos.git
cd ethos
```
2. **Install Poetry:**
```bash
pipx install poetry
```
> **Note:** It is recommended to use `pipx` for installing Poetry, but you can also use `pip` if `pipx` is not available. For more information, please refer to the [official documentation](https://python-poetry.org/docs/).
3. **Configure Poetry to Create Virtual Environment in Project Root:**
```sh
poetry config virtualenvs.in-project true
```
4. **Install Dependencies:**
```bash
poetry install
```
5. **Setup the .env file:** see the `.env.example` for reference and create a `.env` file in the root.
6. **Start the application:**
```bash
poetry run python ethos/main.py
```
### For Distribution:
Coming Soon
## Usage:
https://github.com/user-attachments/assets/e46a7585-ccf1-4e30-bc20-3c48b0767969
### Basic Commands
```bash
/play <track name> # Search and play a track
/pause # Pause current playback
/resume # Resume playback
/volume <0-100> # Set volume level
```
### Queue Management
```bash
/queue-add <track> # Add a track to queue
/show-queue # Display current queue
/qp <number> # Play track number from queue
```
### Keyboard Shortcuts
| Shortcut | Action |
| -------------------- | ---------------- |
| `Ctrl+C` or `Ctrl+Q` | Quit application |
| `Ctrl+M` | Pause playback |
| `Ctrl+R` | Resume playback |
| `Ctrl+1` | Increase volume |
| `Ctrl+2` | Decrease volume |
### Basic Workflow
1. Search for a track:
```bash
/play never gonna give you up
```
2. Select from search results by entering the track number (e.g. 1)
3. Control playback:
- Use `/pause` and `/resume` to control playback
- Adjust volume with `/volume 75`
- View all commands with `/help`
## Troubleshooting
### Common Issues
| Issue | Solution |
| ------------------------- | ------------------------------------------------- |
| No audio output | Check system volume and VLC installation |
| Spotify integration fails | Verify `.env` configuration |
| Installation errors | Update pip: `python -m pip install --upgrade pip` |
## Repository Structure
```bash
ethos/
├── .env.example
├── .gitignore
├── .github/
│ ├── ISSUE_TEMPLATE/
│ └── workflows/
├── docker/
│ ├── dockerfile
│ ├── compose.yaml
│ └── readme.md
├── src/
│ └── img/
├── ethos/
│ ├── __init__.py
│ ├── main.py # entry point of the application.
│ ├── config.py # Manages configuration settings.
│ ├── player.py # Handles the core functionality of the music player.
│ ├── utils.py # Contains utility functions and other helper functions.
│ ├── spotify_importer.py # User's Spotify playlist integration
├── ├── tools/ # Helper tools and utilities
│ │ ├── __init__.py
│ │ ├── endless_playback.py
│ │ └── helper.py
│ ├── ui/ # Terminal UI components
│ │ ├── __init__.py
│ │ ├── rich_layout.py
│ │ ├── styles.tcss
│ │ ├── textual_app.py
│ │ └── ui.py
├── tests/ # Test suite
│ ├── __init__.py
│ ├── conftest.py
│ └── test_player/
│ ├── __init__.py
│ └── test_playback.py
├── LICENSE
├── README.md
├── pyproject.toml # Project configuration and dependencies
├── pytest.ini # PyTest configuration
├── setup.py # Contains the setup script
└── requirements.txt
```
## Contributors
<a href="https://github.com/Itz-Agasta/ethos/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Itz-Agasta/ethos" />
</a>
## License
This project is licensed under the [MIT License](https://github.com/Itz-Agasta/ethos/blob/main/License). See the LICENSE file for more details.
Feel free to Send a [Pull Request](https://github.com/Itz-Agasta/ethos/pulls) if you have improvements or fixes.
Raw data
{
"_id": null,
"home_page": null,
"name": "ethos-cli",
"maintainer": "Agasta",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "rupam.golui@proton.me",
"keywords": "ethos, cli-music-player, spotify, vlc, yt-dlp, audio-player",
"author": "Agasta",
"author_email": "rupam.golui@proton.me",
"download_url": null,
"platform": null,
"description": "**<h1 align=\"center\">Ethos</h1>**\n\n<p align=\"center\">\n <img src=\"src/img/ethos_logo.jpg\" alt=\"Logo of Ethos\" width=\"300\", height=\"300\">\n</p>\n\n<div align=\"center\">\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://github.com/Itz-Agasta/ethos/pulls)\n[](https://codecov.io/gh/Itz-Agasta/ethos)\n[](https://pypi.org/project/ethos/)\n[](https://github.com/Itz-Agasta/ethos/issues)\n[](https://github.com/Itz-Agasta/ethos/stargazers)\n[](https://github.com/Itz-Agasta/ethos/commits/main)\n\n</div>\n\n <p align=\"center\">\n A modern, resource-efficient CLI music player that seamlessly integrates local music libraries with online streaming services. Experience high-quality audio playback, Spotify playlist synchronization, and an intuitive terminal interface designed for both developers and music enthusiasts.\n <br />\n <br />\n <a href=\"https://www.youtube.com/watch?v=E1AjSHxe5NU&feature=youtu.be\">View Demo</a>\n \u00b7\n <a href=\"https://github.com/Itz-Agasta/ethos/issues\">Report Bug</a>\n \u00b7\n <a href=\"https://github.com/Itz-Agasta/ethos/issues\">Request Feature</a>\n \u00b7\n <a href=\"https://github.com/Itz-Agasta/ethos/pulls\">Send a Pull Request</a>\n </p>\n</p>\n\n## Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [Features](#features)\n- [Preview](#preview)\n- [Technologies Used](#technologies-used)\n- [Prerequisites](#prerequisites)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n - [For Development:](#for-development)\n - [For Distribution:](#for-distribution)\n- [Usage:](#usage)\n - [Basic Commands](#basic-commands)\n - [Queue Management](#queue-management)\n - [Keyboard Shortcuts](#keyboard-shortcuts)\n - [Basic Workflow](#basic-workflow)\n- [Troubleshooting](#troubleshooting)\n - [Common Issues](#common-issues)\n- [Repository Structure](#repository-structure)\n- [Contributors](#contributors)\n- [License](#license)\n\n## Features\n\n\ud83c\udfb5 **Universal Accessibility**\n\n- High-quality terminal music playback accessible to both developers and general users\n- Modern and feature-rich interface in your terminal\n- Support for multiple audio formats (MP3, FLAC, WAV, AAC)\n\n\ud83d\udcbb **Resource Efficient**\n\n- Lightweight application with minimal system resource consumption\n- Can be used in devices like Raspberry Pi\n- Optimized for lower-end devices without compromising functionality\n\n\ud83d\udd04 **Unified Music Experience**\n\n- Seamlessly bridges local music libraries with online streaming services\n- All your music needs handled from a single terminal interface\n- Import and sync your Spotify playlists\n- Offline playback for downloaded tracks\n\n\u26a1 **Developer-Centric**\n\n- Terminal-native music solution that integrates with your development workflow\n- Enhances productivity by keeping you in your preferred environment\n\n## Preview\n\n<p align=\"center\">\n <img src=\"src/img/ethos_ui.jpg\" alt=\"Logo of Ethos\">\n</p>\n\n## Technologies Used\n\n- **Backend:** yt-dlp, python-vlc, spotify API, spotipy\n- **Frontend:** Rich, Textual\n- **Language:** Python\n\n## Prerequisites\n\nMake sure you have the following installed:\n\n- Python 3.8 or later\n- pip (Python package installer)\n- VLC media player\n\n## Quick Start\n\n```bash\n# Install Ethos\npip install ethos\n\n# Start playing music\nethos\n```\n\n## Installation\n\n### For Development:\n\n1. **Clone the Repository:**\n ```bash\n git clone https://github.com//Itz-Agasta/ethos.git\n cd ethos\n ```\n2. **Install Poetry:**\n\n ```bash\n pipx install poetry\n ```\n\n > **Note:** It is recommended to use `pipx` for installing Poetry, but you can also use `pip` if `pipx` is not available. For more information, please refer to the [official documentation](https://python-poetry.org/docs/).\n\n3. **Configure Poetry to Create Virtual Environment in Project Root:**\n\n ```sh\n poetry config virtualenvs.in-project true\n ```\n\n4. **Install Dependencies:**\n ```bash\n poetry install\n ```\n5. **Setup the .env file:** see the `.env.example` for reference and create a `.env` file in the root.\n\n6. **Start the application:**\n ```bash\n poetry run python ethos/main.py\n ```\n\n### For Distribution:\n\nComing Soon\n\n## Usage:\n\nhttps://github.com/user-attachments/assets/e46a7585-ccf1-4e30-bc20-3c48b0767969\n\n### Basic Commands\n\n```bash\n/play <track name> # Search and play a track\n/pause # Pause current playback\n/resume # Resume playback\n/volume <0-100> # Set volume level\n```\n\n### Queue Management\n\n```bash\n/queue-add <track> # Add a track to queue\n/show-queue # Display current queue\n/qp <number> # Play track number from queue\n```\n\n### Keyboard Shortcuts\n\n| Shortcut | Action |\n| -------------------- | ---------------- |\n| `Ctrl+C` or `Ctrl+Q` | Quit application |\n| `Ctrl+M` | Pause playback |\n| `Ctrl+R` | Resume playback |\n| `Ctrl+1` | Increase volume |\n| `Ctrl+2` | Decrease volume |\n\n### Basic Workflow\n\n1. Search for a track:\n\n ```bash\n /play never gonna give you up\n ```\n\n2. Select from search results by entering the track number (e.g. 1)\n\n3. Control playback:\n\n- Use `/pause` and `/resume` to control playback\n- Adjust volume with `/volume 75`\n- View all commands with `/help`\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n| ------------------------- | ------------------------------------------------- |\n| No audio output | Check system volume and VLC installation |\n| Spotify integration fails | Verify `.env` configuration |\n| Installation errors | Update pip: `python -m pip install --upgrade pip` |\n\n## Repository Structure\n\n```bash\nethos/\n\u251c\u2500\u2500 .env.example\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 .github/\n\u2502 \u251c\u2500\u2500 ISSUE_TEMPLATE/\n\u2502 \u2514\u2500\u2500 workflows/\n\u251c\u2500\u2500 docker/\n\u2502 \u251c\u2500\u2500 dockerfile\n\u2502 \u251c\u2500\u2500 compose.yaml\n\u2502 \u2514\u2500\u2500 readme.md\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 img/\n\u251c\u2500\u2500 ethos/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 main.py # entry point of the application.\n\u2502 \u251c\u2500\u2500 config.py # Manages configuration settings.\n\u2502 \u251c\u2500\u2500 player.py # Handles the core functionality of the music player.\n\u2502 \u251c\u2500\u2500 utils.py # Contains utility functions and other helper functions.\n\u2502 \u251c\u2500\u2500 spotify_importer.py # User's Spotify playlist integration\n\u251c\u2500\u2500 \u251c\u2500\u2500 tools/ # Helper tools and utilities\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 endless_playback.py\n\u2502 \u2502 \u2514\u2500\u2500 helper.py\n\u2502 \u251c\u2500\u2500 ui/ # Terminal UI components\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 rich_layout.py\n\u2502 \u2502 \u251c\u2500\u2500 styles.tcss\n\u2502 \u2502 \u251c\u2500\u2500 textual_app.py\n\u2502 \u2502 \u2514\u2500\u2500 ui.py\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 conftest.py\n\u2502 \u2514\u2500\u2500 test_player/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 test_playback.py\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml # Project configuration and dependencies\n\u251c\u2500\u2500 pytest.ini # PyTest configuration\n\u251c\u2500\u2500 setup.py # Contains the setup script\n\u2514\u2500\u2500 requirements.txt\n```\n\n## Contributors\n\n<a href=\"https://github.com/Itz-Agasta/ethos/graphs/contributors\">\n <img src=\"https://contrib.rocks/image?repo=Itz-Agasta/ethos\" />\n</a>\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/Itz-Agasta/ethos/blob/main/License). See the LICENSE file for more details.\n\nFeel free to Send a [Pull Request](https://github.com/Itz-Agasta/ethos/pulls) if you have improvements or fixes.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A cross-platform CLI music player delivering local and online music streaming with User's Spotify playlist integration.",
"version": "0.1.0",
"project_urls": {
"documentation": "https://github.com/Itz-Agasta/ethos/blob/master/README.md",
"homepage": "https://github.com/Itz-Agasta/ethos",
"repository": "https://github.com/Itz-Agasta/ethos"
},
"split_keywords": [
"ethos",
" cli-music-player",
" spotify",
" vlc",
" yt-dlp",
" audio-player"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a9a7df890adfa5d315d3324973695481f0c6ee6fbd54991bf2d26a493902b8dd",
"md5": "99f7d524e49837622edd08fa39b4b173",
"sha256": "998c3e3ba5d2da70c2dbff97331efe56bc7c2da2514e53be68c9a50070e6a48c"
},
"downloads": -1,
"filename": "ethos_cli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99f7d524e49837622edd08fa39b4b173",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 23748,
"upload_time": "2025-02-21T08:07:10",
"upload_time_iso_8601": "2025-02-21T08:07:10.430100Z",
"url": "https://files.pythonhosted.org/packages/a9/a7/df890adfa5d315d3324973695481f0c6ee6fbd54991bf2d26a493902b8dd/ethos_cli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-21 08:07:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Itz-Agasta",
"github_project": "ethos",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "yt-dlp",
"specs": [
[
"==",
"2025.01.26"
]
]
},
{
"name": "python-vlc",
"specs": [
[
"==",
"3.0.21203"
]
]
},
{
"name": "spotipy",
"specs": [
[
"==",
"2.25.0"
]
]
},
{
"name": "textual",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.9.4"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.3.4"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.28.1"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
">=",
"3.10.0"
]
]
}
],
"lcname": "ethos-cli"
}
JSON
