ethos-cli

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:

• Clone the Repository:

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

• 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.

• Configure Poetry to Create Virtual Environment in Project Root:

  poetry config virtualenvs.in-project true
  

• Install Dependencies:

  poetry install
  

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

• 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

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

• 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

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.