# Vibe Music

Vibe Music is an adaptive coding atmosphere engine for developers.

It runs music in a detached background `mpv` process and switches the vibe based on what you are doing:

- Change branches: the vibe can change
- Hit errors: intensity can increase
- Deploy: cinematic energy
- Late night: ambient mode
- Deep focus: lo-fi mode

You do not manage playlists. You choose a vibe (or let it auto-pick) and keep coding.

## What it does

- **Plays in the background**: the terminal is never blocked
- **Fast search**: uses `yt-dlp` to find playable YouTube URLs quickly
- **Vibe modes**: `focus`, `debug`, `build`, `deploy`, `late-night`, `hackathon`
- **Auto vibe**: time-of-day + git branch naming rules
- **Optional git hooks**: branch checkout/merge and push can trigger vibe changes
- **Agent-friendly**: JSON command discovery + JSON state output

## Installation

```bash
pip install vibemusic
```

### Requirements

- **mpv**
  - Windows: Vibe Music can auto-download a portable `mpv.exe` if missing
  - macOS: install with `brew install mpv`
  - Linux: install with your package manager (for example `apt install mpv`)
- **yt-dlp** is installed as a Python dependency of this package

### If `vibe` is not found

If your Python scripts folder is not on `PATH`, you may need to add it, or run via the Python module entrypoint:

```bash
python -m vibe commands
```

## Quick start

### Vibe mode

```bash
vibe focus
vibe debug
vibe build
vibe deploy --victory
vibe late-night
vibe hackathon
```

By default, vibe results are filtered to "English-like" titles and queries are biased toward English results.
To disable this filtering:

```bash
vibe focus --lang any
```

To target Tamil results:

```bash
vibe focus --lang tamil
```

### Auto vibe (time + git branch)

```bash
# Polls every 10 seconds and switches when the vibe changes
vibe auto --repo .

# Decide once and exit (useful in scripts)
vibe auto --repo . --once
```

Branch naming rules used by `vibe branch` / `vibe auto`:

- `fix/`, `bug/`, `hotfix/` -> `debug`
- `feature/`, `feat/` -> `build`
- `release/`, `deploy/` -> `deploy`

### React to errors while running a command

Run your tests/build/dev server and switch to a debug vibe when error-like output appears:

```bash
vibe watch -- npm test
```

### Git hooks automation (optional)

Install hooks into any git repo:

```bash
cd /path/to/your/repo
vibe hooks install
```

Uninstall:

```bash
vibe hooks uninstall
```

### Dev Vibe Card (shareable)

```bash
vibe card
vibe card --json
```

## Classic controls

```bash
vibe pause
vibe resume
vibe toggle
vibe stop

vibe next
vibe back
vibe replay   # or: vibe 0

vibe queue
vibe clear
```

Quick flags (single-arg shortcuts):

```bash
vibe -n    # next
vibe -b    # back
vibe -q    # queue
vibe -c    # clear
vibe -p    # pause

## Visualizer

You can show a simple ASCII visualizer for the currently playing track:

```bash
vibe visual
```
```

## For AI agents

Read [AI_INSTRUCTIONS.md](AI_INSTRUCTIONS.md). The key entry points are:

- `vibe commands` (JSON capability list)
- `vibe agent` (JSON player state)
- `vibe ...` (preferred for developer-state requests)

## Architecture (high level)

- **Client**: the `vibe` CLI parses commands and decides what to play
- **Daemon**: an `mpv` process does the actual playback
- **IPC**: named pipe on Windows; Unix socket on macOS/Linux
- **Local state**: stored under `~/.vibe/` (history, cached vibe results, stats)

## Disclaimer and legal notice

This software is provided for educational and research purposes.

- It is a CLI wrapper around `mpv` and `yt-dlp`
- It does not host or distribute copyrighted media
- Streaming behavior depends on third-party services and their terms

## License

GPL-3.0-or-later. See `LICENSE`.