# Playback TUI
A fully local terminal-based music player to play and download spotify/soundcloud playlists
## Features
- 🎵 Modern TUI interface with rich text and interactive elements
- 🎧 Browse and play local music playlists
- 📥 **Download playlists from Spotify and SoundCloud**
- ⏯️ Advanced playback controls (play/pause/skip/previous)
- 🔀 Shuffle and queue management
- 🎛️ Volume control and progress tracking
- ⌨️ Comprehensive keyboard shortcuts
- 🔍 Search functionality with command prompt
- 📊 Metadata display (artist, duration, album art)
- 🌍 **Cross-platform support** - works on Windows, macOS, and Linux
- 🎨 Modern terminal interface with visual selection highlighting
## Prerequisites
### Required Software
- **Python 3.10+** - Required for running the application
- **FFmpeg** - Required for downloading and processing audio from Spotify/SoundCloud
### Platform-Specific Prerequisites
#### macOS
Install via Homebrew:
```bash
brew install python@3.10 ffmpeg
```
#### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install python3.10 python3-pip ffmpeg
```
#### Linux (Fedora/CentOS)
```bash
sudo dnf install python3.10 python3-pip ffmpeg
```
#### Windows
1. Install Python 3.10+ from [python.org](https://python.org)
2. Install FFmpeg from [ffmpeg.org](https://ffmpeg.org/download.html) or via chocolatey:
```cmd
choco install ffmpeg
```
## Installation
1. Clone or download this repository
2. Install the package and dependencies:
```bash
pip install -e .
```
Or install dependencies manually:
```bash
pip install -r requirements.txt
```
## Usage
Run the application:
```bash
playback-tui
```
Or if installed in development mode:
```bash
python player.py
```
## Keyboard Shortcuts
### Main Navigation
- `Space` - Toggle play/pause
- `Enter` - Play selected song and generate new queue
- `Shift+Enter` - Add selected song to top of queue
- `Ctrl+C` - Exit application
### Playback Controls
- `Ctrl+Shift+Right` - Skip to next song
- `Ctrl+Shift+Left` - Previous song or restart current song
- `Ctrl+Shift+Up` - Page up in playlist
- `Ctrl+Shift+Down` - Page down in playlist
- `Cmd+Ctrl+Up` - Move to top of playlist (macOS)
- `Cmd+Ctrl+Down` - Move to bottom of playlist (macOS)
### Features
- `/` - Open command prompt/search
- `Ctrl+Shift+S` - Shuffle playlist
- `Ctrl+Shift+Q` - Open queue screen
- `Ctrl+Shift+T` - Open settings
- `Ctrl+Shift+D` - Open download status screen
- `Ctrl+Shift+U` - Download current playlist
### Modal Navigation
- `Escape` - Close current modal/screen
- `Up/Down` - Navigate lists
- `Enter` - Select item
- `Delete/Backspace` - Remove item (where applicable)
## Configuration
### Music Directory Structure
By default, the application looks for music in:
```
~/Playback-TUI/Playlists/
├── playlist1/
│ ├── song1.mp3
│ ├── song2.mp3
│ └── ...
├── playlist2/
│ ├── song3.mp3
│ └── ...
└── ...
```
You can customize playlist locations in the settings.
### Spotify Integration
For downloading playlists from Spotify, you'll need to:
1. Create a Spotify app at [developer.spotify.com](https://developer.spotify.com/dashboard)
2. Get your Client ID and Client Secret
3. Configure them in the application settings (`Ctrl+Shift+T`)
## Dependencies
### Python Packages
- `textual>=5.3.0` - Modern TUI framework
- `pygame>=2.6.0` - Audio playback
- `mutagen>=1.47.0` - Audio metadata
- `spotipy>=2.25.0` - Spotify API integration
- `yt-dlp>=2025.8.0` - YouTube/SoundCloud downloading
- `requests>=2.32.0` - HTTP requests
All dependencies are automatically installed when using `pip install -e .`
### System Requirements
- **FFmpeg** - Required for audio downloading and processing
- **Python 3.10+** - Required runtime environment
## Troubleshooting
### Audio Issues
- Ensure pygame can access your system's audio drivers
- On Linux, you may need to install additional audio libraries:
```bash
sudo apt install libasound2-dev libpulse-dev
```
### Download Issues
- Verify FFmpeg is properly installed and in your PATH
- Check Spotify credentials are correctly configured
- Ensure internet connectivity for downloading
Raw data
{
"_id": null,
"home_page": null,
"name": "playback-tui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "music, player, terminal, tui, spotify, soundcloud, playlist, downloader",
"author": null,
"author_email": "Ashank Behara <ashank.behara@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b2/54/f2e72c526be7fb7c895dc0189a6444db2918ce7a925d9f7657d2e617cc22/playback_tui-1.2.6.tar.gz",
"platform": null,
"description": "# Playback TUI\n\nA fully local terminal-based music player to play and download spotify/soundcloud playlists\n\n## Features\n\n- \ud83c\udfb5 Modern TUI interface with rich text and interactive elements\n- \ud83c\udfa7 Browse and play local music playlists\n- \ud83d\udce5 **Download playlists from Spotify and SoundCloud**\n- \u23ef\ufe0f Advanced playback controls (play/pause/skip/previous)\n- \ud83d\udd00 Shuffle and queue management\n- \ud83c\udf9b\ufe0f Volume control and progress tracking\n- \u2328\ufe0f Comprehensive keyboard shortcuts\n- \ud83d\udd0d Search functionality with command prompt\n- \ud83d\udcca Metadata display (artist, duration, album art)\n- \ud83c\udf0d **Cross-platform support** - works on Windows, macOS, and Linux\n- \ud83c\udfa8 Modern terminal interface with visual selection highlighting\n\n## Prerequisites\n\n### Required Software\n- **Python 3.10+** - Required for running the application\n- **FFmpeg** - Required for downloading and processing audio from Spotify/SoundCloud\n\n### Platform-Specific Prerequisites\n\n#### macOS\nInstall via Homebrew:\n```bash\nbrew install python@3.10 ffmpeg\n```\n\n#### Linux (Ubuntu/Debian)\n```bash\nsudo apt update\nsudo apt install python3.10 python3-pip ffmpeg\n```\n\n#### Linux (Fedora/CentOS)\n```bash\nsudo dnf install python3.10 python3-pip ffmpeg\n```\n\n#### Windows\n1. Install Python 3.10+ from [python.org](https://python.org)\n2. Install FFmpeg from [ffmpeg.org](https://ffmpeg.org/download.html) or via chocolatey:\n ```cmd\n choco install ffmpeg\n ```\n\n## Installation\n\n1. Clone or download this repository\n2. Install the package and dependencies:\n ```bash\n pip install -e .\n ```\n \n Or install dependencies manually:\n ```bash\n pip install -r requirements.txt\n ```\n\n## Usage\n\nRun the application:\n```bash\nplayback-tui\n```\n\nOr if installed in development mode:\n```bash\npython player.py\n```\n\n## Keyboard Shortcuts\n\n### Main Navigation\n- `Space` - Toggle play/pause\n- `Enter` - Play selected song and generate new queue\n- `Shift+Enter` - Add selected song to top of queue\n- `Ctrl+C` - Exit application\n\n### Playback Controls\n- `Ctrl+Shift+Right` - Skip to next song\n- `Ctrl+Shift+Left` - Previous song or restart current song\n- `Ctrl+Shift+Up` - Page up in playlist\n- `Ctrl+Shift+Down` - Page down in playlist\n- `Cmd+Ctrl+Up` - Move to top of playlist (macOS)\n- `Cmd+Ctrl+Down` - Move to bottom of playlist (macOS)\n\n### Features\n- `/` - Open command prompt/search\n- `Ctrl+Shift+S` - Shuffle playlist\n- `Ctrl+Shift+Q` - Open queue screen\n- `Ctrl+Shift+T` - Open settings\n- `Ctrl+Shift+D` - Open download status screen\n- `Ctrl+Shift+U` - Download current playlist\n\n### Modal Navigation\n- `Escape` - Close current modal/screen\n- `Up/Down` - Navigate lists\n- `Enter` - Select item\n- `Delete/Backspace` - Remove item (where applicable)\n\n## Configuration\n\n### Music Directory Structure\nBy default, the application looks for music in:\n```\n~/Playback-TUI/Playlists/\n\u251c\u2500\u2500 playlist1/\n\u2502 \u251c\u2500\u2500 song1.mp3\n\u2502 \u251c\u2500\u2500 song2.mp3\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 playlist2/\n\u2502 \u251c\u2500\u2500 song3.mp3\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 ...\n```\n\nYou can customize playlist locations in the settings.\n\n### Spotify Integration\nFor downloading playlists from Spotify, you'll need to:\n\n1. Create a Spotify app at [developer.spotify.com](https://developer.spotify.com/dashboard)\n2. Get your Client ID and Client Secret\n3. Configure them in the application settings (`Ctrl+Shift+T`)\n\n## Dependencies\n\n### Python Packages\n- `textual>=5.3.0` - Modern TUI framework\n- `pygame>=2.6.0` - Audio playback\n- `mutagen>=1.47.0` - Audio metadata\n- `spotipy>=2.25.0` - Spotify API integration\n- `yt-dlp>=2025.8.0` - YouTube/SoundCloud downloading\n- `requests>=2.32.0` - HTTP requests\n\nAll dependencies are automatically installed when using `pip install -e .`\n\n### System Requirements\n- **FFmpeg** - Required for audio downloading and processing\n- **Python 3.10+** - Required runtime environment\n\n## Troubleshooting\n\n### Audio Issues\n- Ensure pygame can access your system's audio drivers\n- On Linux, you may need to install additional audio libraries:\n ```bash\n sudo apt install libasound2-dev libpulse-dev\n ```\n\n### Download Issues\n- Verify FFmpeg is properly installed and in your PATH\n- Check Spotify credentials are correctly configured\n- Ensure internet connectivity for downloading\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A terminal-based music player with playlist management and downloading capabilities",
"version": "1.2.6",
"project_urls": {
"Bug Reports": "https://playback-tui.ashankbehara.com",
"Homepage": "https://playback-tui.ashankbehara.com",
"Source": "https://github.com/abehara2/playlist"
},
"split_keywords": [
"music",
" player",
" terminal",
" tui",
" spotify",
" soundcloud",
" playlist",
" downloader"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bfeddd331f1199e39dc8234c2b18060c0a2bba7d935956b27996baa0afe61b23",
"md5": "642c315bda4d088a9be2e0d89c0d090f",
"sha256": "aeb67a8d00f863e1d77d835bfc7cf691636b94e557d777aa382264c988f71a8e"
},
"downloads": -1,
"filename": "playback_tui-1.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "642c315bda4d088a9be2e0d89c0d090f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 31762,
"upload_time": "2025-08-23T08:16:01",
"upload_time_iso_8601": "2025-08-23T08:16:01.317387Z",
"url": "https://files.pythonhosted.org/packages/bf/ed/dd331f1199e39dc8234c2b18060c0a2bba7d935956b27996baa0afe61b23/playback_tui-1.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b254f2e72c526be7fb7c895dc0189a6444db2918ce7a925d9f7657d2e617cc22",
"md5": "862234e3823a2d23a9bf087e7be4af24",
"sha256": "23161a0a633e2182333e1e05cfe9018186cb0e2c56f7c4e2efd8a00f9f7382f8"
},
"downloads": -1,
"filename": "playback_tui-1.2.6.tar.gz",
"has_sig": false,
"md5_digest": "862234e3823a2d23a9bf087e7be4af24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 33374,
"upload_time": "2025-08-23T08:16:02",
"upload_time_iso_8601": "2025-08-23T08:16:02.514284Z",
"url": "https://files.pythonhosted.org/packages/b2/54/f2e72c526be7fb7c895dc0189a6444db2918ce7a925d9f7657d2e617cc22/playback_tui-1.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 08:16:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abehara2",
"github_project": "playlist",
"github_not_found": true,
"lcname": "playback-tui"
}
JSON
