https://github.com/ducks/shelltrax
A cmus (terminal-based music player) clone written in Rust
https://github.com/ducks/shelltrax
Last synced: about 1 month ago
JSON representation
A cmus (terminal-based music player) clone written in Rust
- Host: GitHub
- URL: https://github.com/ducks/shelltrax
- Owner: ducks
- Created: 2025-06-13T01:11:58.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-16T22:56:50.000Z (about 1 year ago)
- Last Synced: 2025-06-16T23:33:02.305Z (about 1 year ago)
- Language: Rust
- Homepage:
- Size: 58.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.dev.md
Awesome Lists containing this project
README
# Developer Guide: shelltrax
This document is for contributors and maintainers of `shelltrax`.
For user-facing instructions, see [README.md](./README.md).
---
## Project Structure
```text
src/
├── app.rs # Core state and logic for App, Screens, Player
├── browser.rs # Directory browsing logic
├── library.rs # Library view, album/artist/track state
├── player.rs # MP3 playback using rodio
├── screens/ # UI rendering per screen
├── ui.rs # Layout split, keybindings, etc.
├── persistence.rs # JSON load/save for artist + track library
```
## Key Features & State
- `App` tracks the active screen (`Library`, `Browser`, etc.)
- Library state is split into:
- Left pane: artists and albums (with expandable tree)
- Right pane: visible tracks, selectable with Tab
- Tracks are tagged using `id3` crate on `.mp3` files
- Playback uses `rodio::Sink` with a manual autoplay toggle
---
## Keybindings
| Key | Action |
|---------------|---------------------------------|
| `1` | Go to Library |
| `5` | Go to Browser |
### Browser View
| Key | Action |
|---------------|---------------------------------|
| `a` | Add file/dir to playlist |
### Library View
| Key | Action |
|---------------|---------------------------------|
| `Tab` | Toggle focus left/right |
| `Enter` | Play selected track |
| `c` | Toggle pause/resume |
| `n` | Next song |
| `p` | Toggle autoplay |
| `Backspace` | Go up a directory (Browser) |
| `Space` | Toggle artist/album view |
| `Up/Down` | Navigate lists |
---
## Persistence
- Library state is saved to `library.json`
- Autoloaded during `App::new()` if it exists
- Only `.mp3` files are supported for now
- Duplicates are ignored silently
---
## Future Todos
- Add `flac` support via `symphonia` or similar
- Implement seeking via Symphonia → rodio integration
- Support playlist screen and queue
- Playback progress bar and time display
- Configurable keybindings
- Better error handling/logging
- Autplay
---
## Contributing
Pull requests welcome! Please:
- Run `cargo fmt`
- Ensure it builds with `cargo check`
- Test playback, UI, and persistence