Metadata-Version: 2.4
Name: kikusan
Version: 0.2.0
Summary: Search and download music from YouTube Music with lyrics
Requires-Python: >=3.12
Requires-Dist: apscheduler>=3.10.4
Requires-Dist: click>=8.0.0
Requires-Dist: croniter>=1.3.0
Requires-Dist: fastapi[standard]>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mutagen>=1.47.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: spotipy>=2.24.0
Requires-Dist: yt-dlp>=2025.12.8
Requires-Dist: ytmusicapi>=1.8.0
Description-Content-Type: text/markdown

# Kikusan

Search and download music from YouTube Music with lyrics.

## Features

- Search YouTube Music
- Download audio in OPUS/MP3/FLAC format
- Playlist support (download entire playlists)
- Quick download (search and download first match)
- Automatic lyrics fetching from lrclib.net (LRC format)
- CLI and web interface
- Docker support

## Installation

```bash
uv sync
```

## Usage

### CLI

```bash
# Search for music
kikusan search "Bohemian Rhapsody"

# Download by video ID
kikusan download bSnlKl_PoQU

# Download by URL
kikusan download --url "https://music.youtube.com/watch?v=bSnlKl_PoQU"

# Search and download first match
kikusan download --query "Bohemian Rhapsody Queen"

# Download entire playlist
kikusan download --url "https://music.youtube.com/playlist?list=..."

# Custom filename format
kikusan download bSnlKl_PoQU --filename "%(title)s"

# Options
kikusan download bSnlKl_PoQU --output ~/Music --format mp3
```

### Web Interface

```bash
kikusan web
# Open http://localhost:8000
```

### Docker

```bash
docker compose up -d
# Open http://localhost:8000
```

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `KIKUSAN_DOWNLOAD_DIR` | `./downloads` | Download directory |
| `KIKUSAN_AUDIO_FORMAT` | `opus` | Audio format (opus, mp3, flac) |
| `KIKUSAN_FILENAME_TEMPLATE` | `%(artist,uploader)s - %(title)s` | Filename template (yt-dlp format) |
| `KIKUSAN_WEB_PORT` | `8000` | Web server port |

## Requirements

- Python 3.12+
- ffmpeg (for audio processing)
