NAMMAN

NAMMAN is a Next.js application that enables guitarists and audio engineers to browse, preview, and sync Neural Amp Modeler (NAM) profiles directly to their local filesystem. It uses the new TONE3000 PKCE OAuth flow for a secure, database-free architecture.

It is a thin, browser-only client over the TONE3000 API: there is no backend, no database, and no separate account — you connect your TONE3000 account via OAuth and everything (search, favorites, tone/model data, downloads) is served by the TONE3000 API.

✨ Key Features

• Direct Local Sync (File System Access API): NAMMAN requests permission to a local folder and writes .nam / .wav model files straight to disk, organized into Amp_and_Cab, Amps, Pedals, Cabinets_IRs, Outboard, Spaces and Experimental subfolders, one folder per tone with a metadata.json.
• One version per capture: Creators often publish the same captures as A1, A2 and custom models under different names. The Versions setting picks per tone: Best version (default: A2 when the tone has it, otherwise A1, custom only as a last resort), A2 only, A1 only, Custom only or Every version. IRs are always included.
• Clean re-syncs: Re-syncing a tone reuses its existing folder (found by tone id, even if the tone was renamed) and moves the files it replaces to _Archive/<Category>/<Pack>/ in the library folder. Nothing is deleted, and nothing is moved if any download failed.
• Library cleanup: Clean up duplicate versions scans every pack folder that has a metadata.json, lists the extra versions it holds (e.g. A1 leftovers next to A2 models) and, after you confirm, moves them to _Archive. Folders without metadata (manual packs, zips) and IRs are never touched.
• Favorites synced to TONE3000: Bookmarking uses the TONE3000 favorite endpoints, so favorites follow your account everywhere.
• Download history: A local (in-browser) record of what you've already synced.

🛠️ Tech Stack

• Framework: Next.js (App Router, client components only)
• Integration: src/lib/tone3000 — a zero-dependency TONE3000 OAuth + API client (ported from the official example app)
• Storage: Tokens in sessionStorage; folder handle + download history in IndexedDB (idb-keyval)
• Icons: Lucide React

🔐 How auth works

OAuth 2.0 with PKCE, entirely in the browser:

1. The user clicks Connect with TONE3000 → startStandardFlow() redirects to TONE3000's authorize endpoint.
2. After sign-in, TONE3000 redirects back to the app origin with a code.
3. handleOAuthCallback() verifies state, exchanges the code for tokens (PKCE — no client secret), and stores them in sessionStorage.
4. T3KClient attaches the Bearer token to every request and refreshes it automatically when it expires.

🚀 Getting Started

Prerequisites

• Node.js 18+
• A TONE3000 publishable key (t3k_pub_…) from Settings → API Keys
• A Chromium-based browser (Chrome, Edge, Brave) for direct folder sync

Installation

npm install

Create a .env (see example.env):

NEXT_PUBLIC_TONE3000_CLIENT_ID=t3k_pub_your_key_here

Open http://localhost:3000 in a Chrome/Edge browser to use NAMMAN. TONE3000 Settings → API Keys (localhost is auto-allowed during development).

npm run dev

Open http://localhost:3000.

The Direct Local Sync feature requires a Secure Context (localhost or https://) and a Chromium-based browser. Other browsers fall back to standard per-file downloads.

🌍 Deployment

Deploy on Vercel: set NEXT_PUBLIC_TONE3000_CLIENT_ID in the project's environment variables and add your production origin as a redirect URI in TONE3000 settings. Vercel provides the HTTPS required by the File System Access API.