# hyprtile-audioplayer

A tiny Linux CLI MP3 player for Hyprland-style setups.

- MP3 decode: `libmpg123`
- Audio output: PulseAudio via `libpulse-simple`
- Control model: daemon + external CLI commands via Unix socket
- Library scan output: JSON in `$HOME/Music` or `$HOME/Musik`

## Dependencies

Arch / Endeavour / Manjaro:

```bash
sudo pacman -S base-devel pkgconf mpg123 libpulse
```

Debian / Ubuntu:

```bash
sudo apt install build-essential pkg-config libmpg123-dev libpulse-dev
```

Fedora:

```bash
sudo dnf install gcc make pkgconf-pkg-config mpg123-devel pulseaudio-libs-devel
```

## Build

```bash
make
```

Optional install:

```bash
sudo make install
```

## Music directory

The app checks:

1. `$HOME/Music`
2. `$HOME/Musik`

The scan writes:

```text
$HOME/Music/hyprtile-audioplayer-library.json
```

or:

```text
$HOME/Musik/hyprtile-audioplayer-library.json
```

## Usage

Scan and write JSON library:

```bash
./hyprtile-audioplayer --scan
```

Print the generated JSON library:

```bash
./hyprtile-audioplayer --library
```

Start player daemon:

```bash
./hyprtile-audioplayer --daemon
```

Start at a specific index:

```bash
./hyprtile-audioplayer --daemon 3
```

In another terminal, control it externally:

```bash
./hyprtile-audioplayer --status
./hyprtile-audioplayer --pause
./hyprtile-audioplayer --resume
./hyprtile-audioplayer --play
./hyprtile-audioplayer --toggle-pause
./hyprtile-audioplayer --stop
./hyprtile-audioplayer --next
./hyprtile-audioplayer --prev
./hyprtile-audioplayer --seek +10
./hyprtile-audioplayer --seek -10
./hyprtile-audioplayer --play-index 4
./hyprtile-audioplayer --quit
```

`--status` returns JSON like:

```json
{
  "app": "hyprtile-audioplayer",
  "running": true,
  "state": "playing",
  "music_dir": "/home/user/Music",
  "library_json": "/home/user/Music/hyprtile-audioplayer-library.json",
  "track": {
    "index": 0,
    "path": "/home/user/Music/song.mp3",
    "filename": "song.mp3",
    "title": "Song Title",
    "artist": "Artist",
    "album": "Album"
  },
  "position_sec": 12.345,
  "duration_sec": 210.000,
  "remaining_sec": 197.655
}
```

## Transport states

`--status` uses these states:

- `playing`: decoding and sending audio to PulseAudio
- `paused`: playback is paused and position is kept
- `stopped`: playback is stopped and current track position is reset to 0
- `idle`: daemon is alive but not actively playing

`--stop` does not kill the daemon. Use `--play`, `--resume`, `--next`, `--prev`, or `--play-index N` to start playback again. Use `--quit` to terminate the daemon.

## Notes

This is intentionally small and hackable. It does not yet implement shuffle, repeat, playlists, or proper XDG user-dirs parsing. It follows the requested `$HOME/Music` / `$HOME/Musik` behavior.
