# rustamp

A tiny, minimalist audio player with a shared core and two front-ends.

Front-ends:

- **rustamp-iced**: desktop GUI built with Iced
- **rustamp-tui**: terminal UI built with Ratatui

Features:

- **Vim-style keyboard controls**: letters + -/+ for volume + [] for seeking
- **State persistence**: playlist + selection + volume saved to disk
- **Translucent window**: black background at 60% opacity (Iced, where supported)

## Requirements

- Rust (stable)
- System audio output device
- For the GUI: a windowing environment (on Linux, a compositor is typically needed for transparency)
- For the TUI: a terminal that supports ANSI escape sequences

## Run

GUI (Iced):

```bash
cargo run -p rustamp-iced
```

TUI:

```bash
cargo run -p rustamp-tui
```

Makefile shortcuts:

```bash
make run-iced
make run-tui
```

## Controls (Vim-ish)

These work in "normal mode" (no Ctrl/Cmd required) in both UIs:

- `o` open file(s) (load paused; GUI multi-select also adds to playlist)
- `a` add files to playlist
- `:` command mode
- `l` load selected (paused)
- `p` play (selected if any; otherwise current)
- `i` pause
- `s` stop
- `t` toggle play/pause
- `-` volume down
- `=`/`+` volume up
- `[` seek back 5s
- `]` seek forward 5s
- `{` seek back 30s (Shift+[)
- `}` seek forward 30s (Shift+])
- `n` next
- `b` previous
- `j` down (select next)
- `k` up (select previous)
- `g` top
- `G` bottom
- `J` move selected track down (Shift+J)
- `K` move selected track up (Shift+K)
- `d` delete selected track
- `z` shuffle toggle
- `r` repeat cycle (off/one/all)
- `H` hold help (shortcuts overlay)

TUI only:

- `q` quit

Command mode (Iced + TUI):

- Enter with `:` and cancel with `Esc` (Iced shows a command bar)
- Run with `Enter`
- Commands: `open`, `add`, `play`, `pause`, `stop`, `toggle`, `next`, `prev`, `load`, `seek`, `rm`/`del` (short aliases allowed)
- Also: `shuffle [on|off|toggle]`, `repeat [off|one|all]`
- `seek` accepts seconds or `mm:ss`/`hh:mm:ss` (prefix `+`/`-` for relative)
- Unknown commands are treated as a path to open; quoted paths are supported

Mouse (Iced):
- Click a track to select
- Double-click a track to play
- Drag the volume slider in the player panel
- Drag the timeline to scrub within the track

## Persistence

rustamp saves state (playlist paths, selection, now playing, volume) to a small JSON file under your OS config directory. Both UIs read and write the same state file.

The location is resolved via the `directories` crate with:

- qualifier: `mx`
- organization: `noumena`
- application: `rustamp`

Typical paths:

- macOS: `~/Library/Application Support/rustamp/state.json` (mapping can vary)
- Linux: `~/.config/rustamp/state.json`
- Windows: `%APPDATA%\rustamp\state.json`

If a saved file no longer exists, it will be skipped on load.

## Project structure

```
crates/
  rustamp-core/  # engine, audio, persistence, input
  rustamp-iced/  # Iced GUI
  rustamp-tui/   # Ratatui TUI
```

## Specs

See `SPEC.md` for command parsing, persistence, and playback behavior.

## Notes

- Supported formats depend on your platform + `rodio` decoders (common ones: mp3/wav/flac/ogg).
- Window transparency may behave differently across OSes and compositors.

## License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <http://unlicense.org/>