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:

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

CI/CD

GitHub Actions runs on push to main:

Install, test, build
Deploy to Cloudflare Pages

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

Processing Pipeline

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

Optional: aubio for fallback BPM/key detection.

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

tokudu/suno