n8n-nodes-toneperfect

This is an n8n community node. It lets you use the TonePerfect pronunciation assessment API, 10 languages, in your n8n workflows.

TonePerfect scores a short scripted recording against the text the speaker was asked to read: 0–100 display grades for the recording, every word and every sound, expected vs heard values and timestamps (Mandarin syllables also get separate initial, final and tone scores). The 10 languages: Mandarin Chinese (zh-CN), English (en-US), French (fr-FR), Spanish (es-419), German (de-DE), Italian (it-IT), Portuguese (pt-BR), Russian (ru-RU), Korean (ko-KR, beta) and Japanese (ja-JP, beta). Every language pack is currently labelled experimental in GET /v1/capabilities.

n8n is a fair-code licensed workflow automation platform.

Installation · Operations · Credentials · Compatibility · Usage · Resources · Version history

Installation

This is a community package for self-hosted n8n. npm publication and verification for the n8n directory are separate processes; this package does not claim verified-node status or n8n Cloud availability. Local publishing runs lint, build and tests without GitHub actions. For local development, run npm ci && npm test.

Follow the installation guide in the n8n community nodes documentation. In short, on a self-hosted n8n: Settings → Community Nodes → Install, enter n8n-nodes-toneperfect, accept the risk prompt and install.

Manual install (queue mode or Docker volumes): npm install n8n-nodes-toneperfect inside ~/.n8n/nodes, then restart n8n.

Operations

Assess inputs:

• Input Binary Field (default data): the recording, 0.15–30 s, at most 10 MB — WAV, MP3, M4A, Ogg or WebM. Use any node that produces binary data (HTTP Request with Response Format: File, Read/Write Files from Disk, Google Drive download, a Webhook/Form upload, Telegram voice note…).
• Reference Text: what the speaker was asked to read. Up to 100 Mandarin characters or 40 words. Free speech is not supported.
• Language: one of the ten locales above.
• Options: Pinyin (Mandarin only, numbered tones such as ni3 hao3), Task (general, connected_speech, isolated_word; Mandarin per-component correction decisions apply only with connected_speech), Idempotency Key, File Name, and Output (Full Response or Summary — overall score, per-word scores and the sounds marked for review).

Each output item also carries _toneperfect: { request_id, idempotency_key, replayed }.

Credentials

1. Create an account at https://api.toneperfect.app/signup — new accounts get 50 free credits, no card needed.
2. Create an API key in the dashboard (tp_live_…).
3. In n8n, create a TonePerfect API credential and paste the key. It is sent as Authorization: Bearer <key>.

The credential test sends a POST /v1/assess with no audio and no Idempotency-Key: a valid key is stopped at 422 invalid_idempotency_key before anything is read, an unknown key gets 401 invalid_api_key. Nothing is charged. (GET /v1/capabilities is public, so it cannot check a key.)

Billing: one credit per started 15 seconds of audio for an assessable result; failed and unassessable requests cost nothing. When the free credits are used up a plan is required — Starter is $10/month (pricing). The node reports 402 errors as payment required, nothing was charged with the reason (subscription_required, insufficient_credits, payment_balance_due).

Compatibility

• Built with @n8n/node-cli 0.51 against n8n-workflow 2.42 (n8nNodesApiVersion: 1, strict mode).
• No runtime dependencies: the multipart upload is built in memory and sent through n8n's own httpRequestWithAuthentication helper.
• Needs an n8n version with community nodes and themed (light/dark) node icons (n8n 1.x or later).

Usage

Retries and double charges. Every assessment carries an Idempotency-Key. If you leave the option empty, the node derives one from the execution ID, the node ID and the item index. n8n's Retry On Fail therefore reuses the same key inside one execution, and the API returns the stored result instead of charging again (_toneperfect.replayed: true). A new execution gets a new key. Set your own key (for example {{ $json.lessonId }}-{{ $json.attempt }}) when you want deduplication across executions. Error messages say which case applies: retry with the SAME key (rate_limit, account_busy, gateway/decoder busy, proxy 502/504) or send a NEW key (a failure already stored under that key, e.g. engine_unavailable after the request was accepted).

Unassessable recordings. A 200 response with assessable: false (silence, a different sentence, unreadable audio) is not a zero score and is not charged; check reason.

Scores. Grades are display scores calibrated per language against native reference recordings. Unsupported dimensions are null. Per-language limitations are listed in GET /v1/capabilities — run the Capability → Get operation to see them.

AI agents. The node is marked usableAsTool, so an n8n AI Agent can call Assess (the Summary output is the compact one to give an agent).

Resources

• n8n community nodes documentation
• TonePerfect API reference · Quickstart · OpenAPI · How scores are produced
• Questions: nik@toneperfect.app

Development

npm install
npm run lint     # n8n community-node lint rules
npm run build
npm test         # offline tests with a mocked n8n context (no network)
npm run dev      # starts a local n8n with this node linked in

Version history

• 0.1.0 — first release: Assess and Capabilities, Bearer credential with a no-charge key check.