@groovesheet/sdk is the official TypeScript client for the REST API, generated from the OpenAPI document, with a groovesheet command line tool in the same package. Node 20 or newer. Source and issues: github.com/groovesheet/groovesheet-sdk.
npm i @groovesheet/sdk
# or, with no install
npx @groovesheet/sdk search "easy on me"
CLI
| Command | What it does |
|---|---|
groovesheet search <query> [--instrument drums] [--format sheet] | Search the library |
groovesheet song <id-or-slug> | Every part of one song and what it has |
groovesheet workflows | The workflow names a transcription can use |
groovesheet transcribe <file> --instrument drums [--wait] [--out dir] | Upload a file, start a job, optionally wait and download |
groovesheet job <id> [--wait] | Poll a job |
groovesheet jobs | Your recent jobs |
groovesheet download <id> [file_key] [--out dir] | Download one output or all of them |
groovesheet account | Plan and minutes left |
groovesheet login --email you@example.com | Sign in: the CLI prints a code and a link, you approve on groovesheet.net |
Global flags: --sandbox (the sandbox: no token, nothing charged), --api-url, --token, --json. Environment: GROOVESHEET_TOKEN, GROOVESHEET_API_URL, GROOVESHEET_SANDBOX=1.
# Try the whole loop without an account
groovesheet --sandbox transcribe any.mp3 --instrument drums --wait --out ./out
SDK
import { GrooveSheet } from '@groovesheet/sdk';
const gs = new GrooveSheet({ token: process.env.GROOVESHEET_TOKEN });
const { tracks } = await gs.searchSongs({ query: 'easy on me' });
const song = await gs.getSong(tracks[0].id);
const job = await gs.transcribe({ file: 'song.mp3', instrument: 'drums' });
const done = await gs.waitForJob(job.workflow_id);
await gs.saveOutputs(done.workflow_id, './out');
new GrooveSheet({ sandbox: true }) points every call at the sandbox. GrooveSheet.login({ email, onCode }) runs the verified-email sign-in from auth.md and resolves to a token set.
In production, transcribe starts a paid job: it uses the account's minutes exactly as an upload on groovesheet.net does. The library and the sandbox are free.
For an AI app rather than code
Use the MCP server instead; the SDK is for programs. An agent that only needs to read about GrooveSheet can use the docs MCP server at https://www.groovesheet.net/mcp/docs or ask POST https://www.groovesheet.net/ask (NLWeb).
