Skip to content

A cross-platform CLI music-player delivering local and online music streaming with User's Spotify playlist integration.

License

Notifications You must be signed in to change notification settings

Itz-Agasta/ethos

Folders and files

NameName
Last commit message
Last commit date

Latest commit

e602cf9 · Feb 24, 2025

History

59 Commits
Feb 21, 2025
Feb 9, 2025
Feb 6, 2025
Feb 8, 2025
Feb 9, 2025
Feb 22, 2025
Feb 9, 2025
Feb 24, 2025
Feb 21, 2025
Feb 21, 2025
Feb 6, 2025
Feb 8, 2025

Repository files navigation

Ethos

Logo of Ethos

Python Version PyPI version Downloads License PRs Welcome GitHub Issues GitHub Stars Last Commit

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

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

Logo of Ethos

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

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.