kikusan 0.1.0__tar.gz

kikusan-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kikusan-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Downloads
+downloads/

kikusan-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

kikusan-0.1.0/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project description
+
+Kikusan is a tool to search and download music from youtube music. It must use yt-dlp in the background. It must be usable through CLI and also have a web app (subcommand "web"). The web app should be really simple, but must support search functionality. It should be deployable with docker and have an example docker-compose file. It must add lyrics via lrc files to the downloaded files (via https://lrclib.net/).

kikusan-0.1.0/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.12-slim
+
+# Install ffmpeg for audio processing
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ffmpeg && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast package management
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml uv.lock ./
+COPY kikusan/ ./kikusan/
+
+# Install dependencies
+RUN uv sync --frozen
+
+# Create downloads directory
+RUN mkdir -p /downloads
+
+ENV KIKUSAN_DOWNLOAD_DIR=/downloads
+ENV KIKUSAN_WEB_PORT=8000
+
+EXPOSE 8000
+
+# Run the web server
+CMD ["uv", "run", "kikusan", "web", "--host", "0.0.0.0"]

kikusan-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: kikusan
+Version: 0.1.0
+Summary: Search and download music from YouTube Music with lyrics
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi[standard]>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mutagen>=1.47.0
+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)

kikusan-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 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)

kikusan-0.1.0/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  kikusan:
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./downloads:/downloads
+    environment:
+      - KIKUSAN_DOWNLOAD_DIR=/downloads
+      - KIKUSAN_AUDIO_FORMAT=opus
+      - KIKUSAN_WEB_PORT=8000
+    restart: unless-stopped

kikusan-0.1.0/kikusan/__init__.py

@@ -0,0 +1,3 @@
+"""Kikusan - Search and download music from YouTube Music with lyrics."""
+
+__version__ = "0.1.0"

kikusan-0.1.0/kikusan/cli.py

@@ -0,0 +1,249 @@
+"""Command-line interface for Kikusan."""
+
+import logging
+from pathlib import Path
+
+import click
+
+from kikusan.config import get_config
+from kikusan.download import download, download_url
+from kikusan.search import search
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+)
+
+
+@click.group()
+@click.version_option()
+def main():
+    """Kikusan - Search and download music from YouTube Music."""
+    pass
+
+
+@main.command()
+@click.argument("query")
+@click.option("-l", "--limit", default=10, help="Maximum number of results")
+def search_cmd(query: str, limit: int):
+    """Search for music on YouTube Music."""
+    results = search(query, limit=limit)
+
+    if not results:
+        click.echo("No results found.")
+        return
+
+    click.echo(f"\nFound {len(results)} results:\n")
+
+    for i, track in enumerate(results, 1):
+        album_info = f" [{track.album}]" if track.album else ""
+        click.echo(f"{i:2}. {track.title} - {track.artist}{album_info}")
+        click.echo(f"    ID: {track.video_id}  Duration: {track.duration_display}")
+        click.echo()
+
+
+# Register search command with alias
+main.add_command(search_cmd, name="search")
+
+
+@main.command()
+@click.argument("video_id", required=False)
+@click.option("--url", "-u", help="YouTube, YouTube Music, or Spotify URL")
+@click.option("--query", "-q", help="Search query (downloads first match)")
+@click.option("--output", "-o", type=click.Path(), help="Output directory")
+@click.option(
+    "--format",
+    "-f",
+    "audio_format",
+    default=None,
+    type=click.Choice(["opus", "mp3", "flac"]),
+    help="Audio format (default: opus)",
+)
+@click.option(
+    "--filename",
+    "-n",
+    "filename_template",
+    default=None,
+    help="Filename template (default: '%(artist,uploader)s - %(title)s')",
+)
+@click.option("--no-lyrics", is_flag=True, help="Skip fetching lyrics")
+def download_cmd(
+    video_id: str | None,
+    url: str | None,
+    query: str | None,
+    output: str | None,
+    audio_format: str | None,
+    filename_template: str | None,
+    no_lyrics: bool,
+):
+    """Download a track by video ID, URL, or search query.
+
+    Examples:
+
+      kikusan download VIDEO_ID
+
+      kikusan download --url "https://music.youtube.com/watch?v=..."
+
+      kikusan download --url "https://music.youtube.com/playlist?list=..."
+
+      kikusan download --url "https://open.spotify.com/playlist/..."
+
+      kikusan download --query "Bohemian Rhapsody Queen"
+    """
+    if not video_id and not url and not query:
+        raise click.UsageError("One of VIDEO_ID, --url, or --query is required")
+
+    config = get_config()
+    output_dir = Path(output) if output else config.download_dir
+    fmt = audio_format or config.audio_format
+    template = filename_template or config.filename_template
+
+    try:
+        # Search and download first match
+        if query:
+            results = search(query, limit=1)
+            if not results:
+                raise click.ClickException(f"No results found for: {query}")
+
+            track = results[0]
+            click.echo(f"Found: {track.title} - {track.artist}")
+
+            audio_path = download(
+                video_id=track.video_id,
+                output_dir=output_dir,
+                audio_format=fmt,
+                filename_template=template,
+                fetch_lyrics=not no_lyrics,
+            )
+            if audio_path:
+                click.echo(f"Downloaded: {audio_path}")
+            return
+
+        # Handle URL (YouTube, YouTube Music, or Spotify)
+        if url:
+            from kikusan.spotify import is_spotify_url
+
+            if is_spotify_url(url):
+                _download_spotify_url(
+                    url=url,
+                    output_dir=output_dir,
+                    audio_format=fmt,
+                    filename_template=template,
+                    fetch_lyrics=not no_lyrics,
+                )
+            else:
+                result = download_url(
+                    url=url,
+                    output_dir=output_dir,
+                    audio_format=fmt,
+                    filename_template=template,
+                    fetch_lyrics=not no_lyrics,
+                )
+
+                if isinstance(result, list):
+                    click.echo(f"Downloaded {len(result)} tracks to {output_dir}")
+                elif result:
+                    click.echo(f"Downloaded: {result}")
+                else:
+                    click.echo("Download completed but could not locate file.")
+            return
+
+        # Download by video ID
+        audio_path = download(
+            video_id=video_id,
+            output_dir=output_dir,
+            audio_format=fmt,
+            filename_template=template,
+            fetch_lyrics=not no_lyrics,
+        )
+
+        if audio_path:
+            click.echo(f"Downloaded: {audio_path}")
+        else:
+            click.echo("Download completed but could not locate file.")
+
+    except Exception as e:
+        raise click.ClickException(str(e))
+
+
+def _download_spotify_url(
+    url: str,
+    output_dir: Path,
+    audio_format: str,
+    filename_template: str,
+    fetch_lyrics: bool,
+) -> None:
+    """Download tracks from a Spotify playlist/album by searching YouTube Music."""
+    from kikusan.spotify import get_tracks_from_url
+
+    spotify_tracks = get_tracks_from_url(url)
+
+    if not spotify_tracks:
+        click.echo("No tracks found in Spotify URL.")
+        return
+
+    click.echo(f"Found {len(spotify_tracks)} tracks in Spotify playlist/album")
+
+    downloaded = 0
+    skipped = 0
+    failed = 0
+
+    for i, sp_track in enumerate(spotify_tracks, 1):
+        click.echo(f"[{i}/{len(spotify_tracks)}] Searching: {sp_track.artist} - {sp_track.name}")
+
+        # Search YouTube Music for this track
+        results = search(sp_track.search_query, limit=1)
+
+        if not results:
+            click.echo(f"  Not found on YouTube Music, skipping")
+            failed += 1
+            continue
+
+        yt_track = results[0]
+        click.echo(f"  Found: {yt_track.title} - {yt_track.artist}")
+
+        try:
+            audio_path = download(
+                video_id=yt_track.video_id,
+                output_dir=output_dir,
+                audio_format=audio_format,
+                filename_template=filename_template,
+                fetch_lyrics=fetch_lyrics,
+            )
+
+            if audio_path and "Skipping" not in str(audio_path):
+                downloaded += 1
+            else:
+                skipped += 1
+
+        except Exception as e:
+            click.echo(f"  Failed: {e}")
+            failed += 1
+
+    click.echo(f"\nCompleted: {downloaded} downloaded, {skipped} skipped, {failed} failed")
+
+
+main.add_command(download_cmd, name="download")
+
+
+@main.command()
+@click.option("--host", default="0.0.0.0", help="Host to bind to")
+@click.option("--port", "-p", default=None, type=int, help="Port to listen on")
+def web(host: str, port: int | None):
+    """Start the web interface."""
+    import uvicorn
+
+    from kikusan.config import get_config
+
+    config = get_config()
+    server_port = port or config.web_port
+
+    click.echo(f"Starting web server at http://{host}:{server_port}")
+
+    from kikusan.web.app import app
+
+    uvicorn.run(app, host=host, port=server_port)
+
+
+if __name__ == "__main__":
+    main()

kikusan-0.1.0/kikusan/config.py

@@ -0,0 +1,42 @@
+"""Configuration handling for Kikusan."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+# Default filename template: Artist - Title
+DEFAULT_FILENAME_TEMPLATE = "%(artist,uploader)s - %(title)s"
+
+
+@dataclass
+class Config:
+    """Application configuration."""
+
+    download_dir: Path
+    audio_format: str
+    filename_template: str
+    web_port: int
+    spotify_client_id: str | None
+    spotify_client_secret: str | None
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        """Create config from environment variables with defaults."""
+        return cls(
+            download_dir=Path(os.getenv("KIKUSAN_DOWNLOAD_DIR", "./downloads")),
+            audio_format=os.getenv("KIKUSAN_AUDIO_FORMAT", "opus"),
+            filename_template=os.getenv("KIKUSAN_FILENAME_TEMPLATE", DEFAULT_FILENAME_TEMPLATE),
+            web_port=int(os.getenv("KIKUSAN_WEB_PORT", "8000")),
+            spotify_client_id=os.getenv("SPOTIFY_CLIENT_ID"),
+            spotify_client_secret=os.getenv("SPOTIFY_CLIENT_SECRET"),
+        )
+
+    @property
+    def spotify_configured(self) -> bool:
+        """Check if Spotify credentials are configured."""
+        return bool(self.spotify_client_id and self.spotify_client_secret)
+
+
+def get_config() -> Config:
+    """Get the current configuration."""
+    return Config.from_env()