Mrixs
8e0ad5c90a
Document project structure, configuration, build/run instructions, storage schema, and ID3 tag mapping.
131 lines
3.7 KiB
Markdown
131 lines
3.7 KiB
Markdown
# ym-dl
|
||
|
||
Yandex Music downloader — Go service for monitoring and downloading tracks/albums from Yandex Music for configured artists.
|
||
|
||
## Features
|
||
|
||
- **Token-only authentication** via Yandex Music OAuth token
|
||
- **Artist monitoring** — periodic check for new tracks and albums
|
||
- **Track & album download** with direct URL signing
|
||
- **SQLite storage index** with migration from legacy JSON index
|
||
- **Rich ID3 tags** — genre, comment, lyrics, publisher, ISRC, copyright, original year, encoded by
|
||
- **High-resolution covers** (1000×1000) embedded in MP3 tags and saved as `cover.jpg`
|
||
- **Idempotent downloads** — tracks are not re-downloaded
|
||
- **Structured JSON logging** for Docker environments
|
||
|
||
## Project structure
|
||
|
||
```
|
||
ym-dl/
|
||
├── cmd/ym-dl/ # Main entry point
|
||
├── internal/
|
||
│ ├── config/ # Configuration loading (artist IDs, API credentials)
|
||
│ ├── downloader/ # Download orchestration
|
||
│ ├── monitor/ # Periodic check logic for new releases
|
||
│ ├── storage/ # SQLite storage for downloaded tracks/albums
|
||
│ └── yandex/ # Yandex Music API client wrapper
|
||
├── Dockerfile # Multi-stage build
|
||
├── docker-compose.yml # Service definition
|
||
├── config.yaml.example # Sample configuration
|
||
├── docs/yandex-music.yaml # Yandex Music OpenAPI spec
|
||
└── README.md
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Create `config.yaml` based on `config.yaml.example`:
|
||
|
||
```yaml
|
||
yandex:
|
||
token: "oauth_token" # Yandex Music OAuth token (required)
|
||
|
||
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, e.g. "24h", "6h30m")
|
||
```
|
||
|
||
### Authentication
|
||
|
||
Only OAuth token is supported. Obtain a token from Yandex OAuth and set it in `yandex.token`.
|
||
|
||
## Build & Run
|
||
|
||
### Locally
|
||
|
||
```bash
|
||
go build -o bin/ym-dl ./cmd/ym-dl
|
||
go run ./cmd/ym-dl --config config.yaml
|
||
```
|
||
|
||
### Docker Compose
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
Mount your config at `/config.yaml` and storage at `/data`:
|
||
|
||
```yaml
|
||
# docker-compose.yml override
|
||
volumes:
|
||
- ./config.yaml:/config.yaml
|
||
- ./data:/data
|
||
```
|
||
|
||
## Development
|
||
|
||
```bash
|
||
# Run tests
|
||
go test ./...
|
||
|
||
# Run single test
|
||
go test -v -run TestName ./internal/...
|
||
|
||
# Lint
|
||
golangci-lint run
|
||
|
||
# Build
|
||
go build -o bin/ym-dl ./cmd/ym-dl
|
||
```
|
||
|
||
## Storage
|
||
|
||
The download index is stored in SQLite (`index.db` inside the storage path). On first launch, an existing legacy `.index.json` is automatically migrated to SQLite and removed.
|
||
|
||
Albums are considered fully downloaded only when all expected tracks (per `track_count` from Yandex API) are present in the index. Compilation albums where the artist appears on only some tracks are downloaded completely.
|
||
|
||
## ID3 Tags
|
||
|
||
MP3 files are tagged with:
|
||
|
||
| Frame | Field | Source |
|
||
|-------|-------|--------|
|
||
| TIT2 | Title | track title |
|
||
| TPE1 | Artist | all track artists |
|
||
| TPE2 | Album Artist | album artist |
|
||
| TALB | Album | album title |
|
||
| TYER | Year | release year |
|
||
| TCON | Genre | track/album genre |
|
||
| TRCK | Track number | position in album |
|
||
| TPOS | Disc number | volume in album |
|
||
| TCOM | Composer | (reserved) |
|
||
| TPUB | Publisher | album label |
|
||
| TENC | Encoded by | "ym-dl" |
|
||
| TCOP | Copyright | album catalog number |
|
||
| TORY | Original year | release date year |
|
||
| TSRC | ISRC | (reserved) |
|
||
| COMM | Comment | album description |
|
||
| USLT | Lyrics | track lyrics |
|
||
| APIC | Cover art | 1000×1000 JPEG |
|
||
| TXXX | Yandex IDs | track/album/artist IDs |
|
||
|
||
## License
|
||
|
||
Private project. |