kikusan 0.2.0__tar.gz

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

@@ -0,0 +1,80 @@
+name: Publish project
+
+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
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Extract tag name
+        id: vars
+        run: echo "tag=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: |
+            ghcr.io/dadav/kikusan:${{ steps.vars.outputs.tag }}
+            ghcr.io/dadav/kikusan:latest

kikusan-0.2.0/.gitignore

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

kikusan-0.2.0/.python-version

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

kikusan-0.2.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.2.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 README.md 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.2.0/PKG-INFO

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

kikusan-0.2.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.2.0/cron.example.yaml

@@ -0,0 +1,49 @@
+# Kikusan Cron Configuration Example
+#
+# This file defines playlists to be monitored and synchronized automatically
+# according to cron schedules.
+
+playlists:
+  # Playlist name - used for state tracking and M3U playlist file
+  favorites:
+    # YouTube, YouTube Music, or Spotify playlist URL
+    url: https://open.spotify.com/playlist/4X7NjgnVWsjOLNmZtUfFUK?si=93678213885d4c05
+
+    # Sync behavior:
+    # - false: Keep local files even if removed from playlist
+    # - true: Delete local files when removed from playlist
+    sync: false
+
+    # Cron schedule expression (standard cron format)
+    # Format: minute hour day month weekday
+    # Examples:
+    #   "5 4 * * *"        - Daily at 04:05
+    #   "0 */2 * * *"      - Every 2 hours
+    #   "0 0 * * 0"        - Weekly on Sunday at midnight
+    #   "*/30 * * * *"     - Every 30 minutes
+    schedule: "5 4 * * *"
+
+  # Another playlist example with sync enabled
+  mixed:
+    url: https://open.spotify.com/playlist/1fA6WesRnRQoQl5Nj4sk7S?si=6acbec5276ed4f13
+
+    # This playlist will delete local files when tracks are removed
+    sync: true
+
+    # Run at minute 23 past every 2nd hour from 0 through 20
+    schedule: "23 0-20/2 * * *"
+
+  # YouTube Music playlist example
+  # workout:
+  #   url: https://music.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
+  #   sync: false
+  #   schedule: "0 6 * * *"  # Daily at 06:00
+
+# Usage:
+#   kikusan cron                          # Run continuously
+#   kikusan cron --config cron.yaml       # Specify config file
+#   kikusan cron --once                   # Sync all playlists once and exit
+#   kikusan cron --output /custom/path    # Override download directory
+#
+# State files are stored in: {download_dir}/.kikusan/state/
+# M3U playlists are stored in: {download_dir}/{playlist_name}.m3u

kikusan-0.2.0/docker-compose.cron.yml

@@ -0,0 +1,77 @@
+# Docker Compose configuration for Kikusan Cron
+#
+# This docker-compose file runs the Kikusan cron service for automatic
+# playlist synchronization based on schedules defined in cron.yaml.
+
+services:
+  # Kikusan cron service - monitors and syncs playlists
+  kikusan-cron:
+    build: .
+    container_name: kikusan-cron
+    command: ["uv", "run", "kikusan", "cron", "--config", "/config/cron.yaml"]
+
+    volumes:
+      # Mount downloads directory (contains audio files and state)
+      - ./downloads:/downloads
+
+      # Mount cron configuration file (read-only)
+      - ./cron.yaml:/config/cron.yaml:ro
+
+    environment:
+      # Download directory inside container
+      - KIKUSAN_DOWNLOAD_DIR=/downloads
+
+      # Audio format (opus, mp3, or flac)
+      - KIKUSAN_AUDIO_FORMAT=opus
+
+      # Spotify credentials (required for Spotify playlists)
+      # Create an app at https://developer.spotify.com/dashboard
+      - SPOTIFY_CLIENT_ID=${SPOTIFY_CLIENT_ID}
+      - SPOTIFY_CLIENT_SECRET=${SPOTIFY_CLIENT_SECRET}
+
+      # Optional: Filename template
+      # - KIKUSAN_FILENAME_TEMPLATE=%(artist,uploader)s - %(title)s
+
+    restart: unless-stopped
+
+    # Optional: Health check
+    # healthcheck:
+    #   test: ["CMD", "test", "-d", "/downloads/.kikusan/state"]
+    #   interval: 5m
+    #   timeout: 10s
+    #   retries: 3
+
+  # Optional: Run web UI alongside cron service
+  # Uncomment the section below to enable the web interface
+
+  # kikusan-web:
+  #   build: .
+  #   container_name: kikusan-web
+  #   command: ["uv", "run", "kikusan", "web", "--host", "0.0.0.0", "--port", "8000"]
+  #
+  #   ports:
+  #     - "8000:8000"
+  #
+  #   volumes:
+  #     - ./downloads:/downloads
+  #
+  #   environment:
+  #     - KIKUSAN_DOWNLOAD_DIR=/downloads
+  #     - KIKUSAN_AUDIO_FORMAT=opus
+  #     - KIKUSAN_WEB_PORT=8000
+  #
+  #   restart: unless-stopped
+
+# Usage:
+#   1. Create cron.yaml with your playlist configurations
+#   2. Set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET in .env file
+#   3. Run: docker-compose -f docker-compose.cron.yml up -d
+#   4. View logs: docker-compose -f docker-compose.cron.yml logs -f kikusan-cron
+#   5. Stop: docker-compose -f docker-compose.cron.yml down
+#
+# Files structure:
+#   ./downloads/                    - Downloaded audio files
+#   ./downloads/.kikusan/state/     - State files (playlist tracking)
+#   ./downloads/{playlist}.m3u      - Generated M3U playlists
+#   ./cron.yaml                     - Cron configuration
+#   ./.env                          - Environment variables (optional)

kikusan-0.2.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.2.0/kikusan/__init__.py

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