View as Markdownllms.txt

SDK and CLI

The official GrooveSheet npm package, @groovesheet/sdk, and its groovesheet command line tool: search the library, transcribe a file, poll the job, download the results.

@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

CommandWhat 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 workflowsThe 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 jobsYour recent jobs
groovesheet download <id> [file_key] [--out dir]Download one output or all of them
groovesheet accountPlan and minutes left
groovesheet login --email you@example.comSign 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).

← REST APIFAQ →