Mrixs
fe62910311
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)
91 lines
2.6 KiB
Markdown
91 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```yaml
|
|
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 |