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 · Documentation . 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.9 or later
• pipx (Recommended) or pip
• VLC media player

For detailed system-specific requirements and setup instructions, please refer to our official documentation.

Quick Start

# Install using pipx (recommended)
pipx install ethos-cli

# Or using pip
pip install ethos-cli

# 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. Install Development Dependencies:

   poetry install --with dev # install all the necessary dependencies for development. (eg: pytest)

6. Setup the .env file: see the .env.example for reference and create a .env file in the root.

7. Start the application:

   poetry run ethos

For Distribution:

Visit the Official Ethos Documentation for detailed installation instructions based on your system.

Usage:

ethos_demo.mp4

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

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:

   /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

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.