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.
View Demo
·
Report Bug
·
Request Feature
·
Send a Pull Request
- Table of Contents
- Features
- Preview
- Technologies Used
- Prerequisites
- Quick Start
- Installation
- Usage:
- Troubleshooting
- Repository Structure
- Contributors
- License
🎵 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
- Backend: yt-dlp, python-vlc, spotify API, spotipy
- Frontend: Rich, Textual
- Language: Python
Make sure you have the following installed:
- Python 3.8 or later
- pip (Python package installer)
- VLC media player
# Install Ethos
pip install ethos
# Start playing music
ethos
-
Clone the Repository:
git clone https://github.com//Itz-Agasta/ethos.git cd ethos
-
Set Up a Virtual Environment:
python -m venv .venv source .venv/bin/activate # For MacOS/Linux .venv\Scripts\activate # For Windows
-
Install Dependencies:
pip install -r requirements.txt
-
Setup the .env file: see the
.env.example
for reference and create a.env
file in the root. -
Start the application:
python3 main.py #for linux/macOS python main.py #for windows
Coming Soon
ethos_demo.mp4
/play <track name> # Search and play a track
/pause # Pause current playback
/resume # Resume playback
/volume <0-100> # Set volume level
/queue-add <track> # Add a track to queue
/show-queue # Display current queue
/qp <number> # Play track number from queue
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 |
-
Search for a track:
/play never gonna give you up
-
Select from search results by entering the track number (e.g. 1)
-
Control playback:
- Use
/pause
and/resume
to control playback - Adjust volume with
/volume 75
- View all commands with
/help
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 |
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
This project is licensed under the MIT License. See the LICENSE file for more details.
Feel free to Send a Pull Request if you have improvements or fixes.