Ethos

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

• Table of Contents
• Features
• Preview
• Technologies Used
• Prerequisites
• Quick Start
• Installation
  • For Development:
  • For Distribution:
• Usage:
  • Basic Commands
  • Queue Management
  • Keyboard Shortcuts
  • Basic Workflow
• Troubleshooting
  • Common Issues
• Repository Structure
• Contributors
• 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

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

# Install Ethos
pip install ethos

# Start playing music
ethos

Installation

For Development:

1. Clone the Repository:

   git clone https://github.com//Itz-Agasta/ethos.git
   cd ethos
   

2. Install Poetry:

   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.

3. Configure Poetry to Create Virtual Environment in Project Root:

   poetry config virtualenvs.in-project true
   

4. Install Dependencies:

   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:

   poetry run python ethos/main.py
   

For Distribution:

Coming Soon

Usage:

https://github.com/user-attachments/assets/e46a7585-ccf1-4e30-bc20-3c48b0767969

Basic Commands

/play <track name>     # Search and play a track
/pause                 # Pause current playback
/resume                # Resume playback
/volume <0-100>        # Set volume level

Queue Management

/queue-add <track>    # Add a track to queue
/show-queue           # Display current queue
/qp <number>          # Play track number from queue

Keyboard Shortcuts

Basic Workflow

1. Search for a track:

   /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

Repository Structure

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

License

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.