tokudu-suno

A music library for TOKUDU tracks generated by Suno. Includes a processing pipeline (BPM/key detection, categorization, playlist generation, Traktor integration) and a static web UI hosted on Cloudflare Pages.

Architecture

Component	URL	Infrastructure
Website	suno.tokudu.com	Cloudflare Pages
Audio & data	suno-audio.tokudu.com	Cloudflare R2 bucket

The static site loads library.json and streams audio from the R2 bucket at runtime.

Getting Started

Prerequisites: Node.js 20+, pnpm 9.15+

# 1. Copy .env.keys from 1Password ("Github: tokudu/suno (.env.keys)")
# 2. Run setup (installs deps, configures Cloudflare, provisions R2 bucket)
./setup

Scripts

Command	Description
pnpm sync	Full pipeline: download tracks from R2 → process → upload
pnpm download	Force download all tracks from R2
pnpm upload	Force upload all tracks to R2
pnpm process	Run processing pipeline only (BPM, key, playlists)
pnpm dev	Start Next.js dev server
pnpm build	Build static site
pnpm deploy	Build and deploy to Cloudflare Pages
pnpm test	Run tests
pnpm env:decrypt	Decrypt .env.encrypted → .env
pnpm env:encrypt	Encrypt .env → .env.encrypted

Environment

File	Contains	Checked in
.env.development	Public URLs for local dev	Yes
.env.production	Public URLs for production	Yes
.env.encrypted	Cloudflare secrets (encrypted via dotenvx)	Yes
.env.keys	Private decryption key	No
.env	Decrypted secrets (generated by pnpm env:decrypt)	No

The .env.keys file is stored in 1Password as "Github: tokudu/suno (.env.keys)".

Cloudflare API Token

The ./setup script will prompt for a Cloudflare API token if one isn't configured:

1. Go to Cloudflare API Tokens
2. Click Create Token → Custom token
3. Set permissions: Workers R2 Storage (Edit), Cloudflare Pages (Edit), Zone > Zone (Read)
4. Restrict to your account under Account Resources
5. Copy the token and paste when prompted

CI/CD

GitHub Actions runs on push to main:

1. Install, test, build
2. Deploy to Cloudflare Pages

Required GitHub secret: DOTENV_PRIVATE_KEY (from .env.keys).

Processing Pipeline

1. Import — Load tracks-list.csv, match audio/metadata files
2. Process — Extract BPM, musical key, metadata from ID3 tags and text
3. Analyze — Categorize tracks, generate playlists (dynamic, DJ sets, static)
4. Export — Copy MP3s to Traktor directory, generate M3U8 playlists
5. Report — Generate interactive HTML report

Optional: aubio for fallback BPM/key detection.

Set EXPORT_DIR to customize the Traktor export destination (default: ~/Music/Suno).