0 Fork 0

Files

T

Mrixs fe62910311 Initial commit: ym-dl with yandex-music-api-go library migration

Migrate ym-dl from custom oapi-codegen Yandex Music API client to external
gitea.mrixs.me/Mrixs/yandex-music-api-go library with token-only authentication.

Key changes:
- Replace custom Yandex API client with yandexmusic library wrapper
- Token-based OAuth authentication only (no username/password fallback)
- SQLite storage index with JSON index migration path
- Extended ID3 tag support: genre, comment, lyrics, publisher, ISRC, copyright
- High-resolution album covers (1000x1000)
- Fixed album download check (requires all tracks, not just one)

2026-10-17 17:09:42 +03:00

2.6 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ym-dl — A Go service for monitoring and downloading tracks/albums from Yandex Music for configured artists.

Language: Go (strict typing, idiomatic patterns)
Runtime: Docker / Docker Compose
API: Yandex Music (OpenAPI spec at docs/yandex-music.yaml)
Config: YAML file listing artist IDs to monitor

Architecture

ym-dl/
├── cmd/ym-dl/           # Main entry point
├── internal/
│   ├── config/          # Configuration loading (artist IDs, API credentials)
│   ├── yandex/          # Yandex Music API client (generated from OpenAPI)
│   ├── storage/         # Local file storage for downloaded tracks/albums
│   ├── monitor/         # Periodic check logic for new releases
│   └── downloader/      # Download orchestration
├── docker-compose.yml   # Service definition
├── Dockerfile           # Multi-stage build
└── config.yaml.example  # Sample configuration

Development Commands

# Build
go build -o bin/ym-dl ./cmd/ym-dl

# Run locally
go run ./cmd/ym-dl --config config.yaml

# Run with Docker Compose
docker compose up --build

# Run tests
go test ./...

# Run single test
go test -v -run TestName ./internal/...

# Lint
golangci-lint run

# Generate API client from OpenAPI
oapi-codegen -generate types,client -package yandex docs/yandex-music.yaml > internal/yandex/client.gen.go

Configuration

config.yaml structure:

yandex:
  token: "oauth_token"        # Or use username/password for token exchange
  username: "login"
  password: "password"

artists:
  - id: 12345                 # Artist ID from Yandex Music
  - id: 67890

storage:
  path: "/data/music"         # Local path for downloads
  organize: true              # Organize into Artist/Album/Track structure

monitor:
  interval: "24h"             # Check interval (duration string)

Key Implementation Notes

Authentication: Support both OAuth token and username/password (token exchange via /token endpoint)
Rate limiting: Respect Yandex API limits; implement exponential backoff
Idempotency: Track downloaded files by Yandex track/album ID to avoid re-downloads
Progress: Structured logging (JSON) for Docker environments

Docker

Multi-stage build: builder (Go 1.23+) → runtime (distroless or alpine). Mount config at /config.yaml, storage at /data.

Testing

Unit tests for config, storage, monitor logic
Integration tests against mocked Yandex API (use net/http/httptest)
No real API calls in CI

2.6 KiB Raw Permalink Blame History