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

 

History

49 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ethos

Logo of Ethos

Python Version License PRs Welcome Code Coverage Downloads 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 · 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.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. Set Up a Virtual Environment:

    python -m venv .venv
    source .venv/bin/activate       # For MacOS/Linux
    .venv\Scripts\activate          # For Windows
  3. Install Dependencies:

    pip install -r requirements.txt
  4. Setup the .env file: see the .env.example for reference and create a .env file in the root.

  5. Start the application:

    python3 main.py #for linux/macOS
    python main.py #for windows

For Distribution:

Coming Soon

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.

About

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

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Contributors 3

  •  
  •  
  •  

Languages