What we're building

A Node.js script that:

1. checks which languages a pronunciation-scoring API supports and what its known limits are,
2. sends a learner's recording of a known Japanese sentence,
3. prints a score for the whole sentence and for each phrase, with timestamps and a "should we correct this?" decision,
4. and then shows what happens when the learner reads the wrong sentence, which is where the interesting design decision is.

This is scripted speech scoring: you tell the API what the learner was supposed to say. It's not speech-to-text.

Prerequisites

• Node.js 18+ (uses the built-in fetch, FormData and Blob)
• An API key from https://api.toneperfect.app/signup (new accounts get 50 free credits, no card)
• A short recording: WAV, MP3, M4A, Ogg or WebM, 0.15 to 120 seconds, under 10 MB

If you don't have a learner recording handy, macOS text-to-speech is enough to test the wiring:

say -v Kyoko "日本語を勉強しています" -o ja.aiff
ffmpeg -y -i ja.aiff -ar 16000 -ac 1 ja.wav

A TTS voice is close to native, so expect high scores. It's only for checking that the plumbing works.

Step 1: read the capabilities first (no key needed)

const caps = await (await fetch('https://api.toneperfect.app/v1/capabilities')).json();
const ja = caps.languages.find((l) => l.locale === 'ja-JP');
console.log(ja.status, ja.dimensions, ja.limitations);

Output on 7 October 2026 (trimmed):

experimental [ 'pronunciation', 'completeness' ]
New pack (beta): native-reference scale, not yet calibrated on graded learner recordings;
a different sentence can still score around 30, and kanji are read with a dictionary that
can miss context-dependent readings (今日は). Text is split into bunsetsu-like units;
pitch accent is not scored.

Worth reading before you put a number in front of a learner:

• Japanese is a beta pack.
• It scores pronunciation and completeness. It does not score pitch accent.
• Kanji readings come from a dictionary, so pass context-dependent words (今日は) in kana.
• The "words" you get back are phrase-like units (日本語を / 勉強しています), not dictionary words.

Step 2: the scoring script

// assess-ja.mjs
// Node 18+. Run: TONEPERFECT_API_KEY=tp_live_... node assess-ja.mjs ja.wav "日本語を勉強しています"
import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const API = 'https://api.toneperfect.app';
const [file = 'ja.wav', text = '日本語を勉強しています'] = process.argv.slice(2);

// 1) Is the Japanese pack available? (no key needed)
const caps = await (await fetch(`${API}/v1/capabilities`)).json();
const ja = caps.languages.find((l) => l.locale === 'ja-JP');
if (!ja?.available) throw new Error('ja-JP is not available right now');
console.log(`ja-JP: ${ja.status}, dimensions=${ja.dimensions.join(',')}, max ${ja.max_duration_seconds}s`);

// 2) Send the recording plus the text the learner was asked to read
const form = new FormData();
form.append('audio', new Blob([await readFile(file)], { type: 'audio/wav' }), file);
form.append('text', text);
form.append('language', 'ja-JP');

const res = await fetch(`${API}/v1/assess`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TONEPERFECT_API_KEY}`,
    // One key per recording attempt; reuse it only to retry the same attempt
    'Idempotency-Key': `ja-${randomUUID()}`,
  },
  body: form,
});
const r = await res.json();
if (!res.ok) throw new Error(`${res.status} ${r.error?.code}: ${r.error?.message}`);

// 3) Silence etc. comes back as 200 with assessable=false (and is not charged)
if (!r.assessable) {
  console.log(`not assessable: ${r.reason}`);
  process.exit(0);
}

console.log(`overall ${r.scores.overall}  pronunciation ${r.scores.pronunciation}  completeness ${r.scores.integrity}`);
for (const w of r.words) {
  // decision is review / uncertain / no_correction
  const flag = w.decision === 'review' ? '  <- review' : '';
  console.log(`${w.word}\t${w.score}\t${w.start_ms}-${w.end_ms}ms\t${w.decision}${flag}`);
}
console.log('credits charged:', r.billing.credits, 'free left:', r.billing.free_credits);

Three things that tripped me up the first time:

• Don't set Content-Type yourself. Pass the FormData and let fetch add the multipart boundary.
• Idempotency-Key is required. Reuse the same key only when retrying the same recording after a network error, so a retry can't charge twice.
• Keep the key on your server. A browser or mobile app should call your backend, which calls the API.

Step 3: the happy path

Reading the right sentence:

ja-JP: experimental, dimensions=pronunciation,completeness, max 30s
overall 83.1  pronunciation 90.6  completeness 91.6
日本語を	95.5	0-676ms	no_correction
勉強しています	86.6	676-2016ms	no_correction
credits charged: 1 free left: 49

Each phrase comes with start_ms / end_ms, so "replay just this part" or highlighting the phrase is easy to build.

The 0–100 score is a display grade, not a "% native" figure. Whether to tell a learner to fix something is meant to come from decision (for example, only interrupt on review), not from a score threshold you pick.

Step 4: the wrong sentence (the useful part)

Same text ("日本語を勉強しています"), but the recording says "ちょっと待ってください" (a completely different sentence):

overall 34.4  pronunciation 54.1  completeness 66.2
日本語を	85.1	0-445ms	no_correction
勉強しています	64.9	445-1435ms	no_correction

The overall score drops to 34.4, but the first phrase still scores 85.1 even though it was never said. That's exactly the "a different sentence can still score around 30" caveat from the capabilities response. If your UI only shows per-phrase scores, a learner who read the wrong line could see a green "日本語を".

So the order of checks I'd use:

1. assessable first.
2. Then scores.overall and scores.integrity (completeness) to decide whether they read the right sentence at all. Pick the threshold from your own recordings.
3. Only then show per-phrase scores and decisions.

Japanese-specific notes

• Pitch accent (高低) is not scored; consonants, vowels and length are.
• Write numbers as words.
• Up to 120 s and 10 MB per recording. One credit per started 15 s of audio.
• Unassessable requests (assessable: false) are not charged.
• Audio is deleted after scoring and not used for training.

Wrapping up

The Japanese pack is still beta and not yet calibrated on graded learner recordings. Its limits show up in /v1/capabilities and in the scores themselves, so most of the work on the integration side is choosing the order of checks, as in step 4.

TonePerfect API (I'm the maker): https://api.toneperfect.app · docs: https://api.toneperfect.app/docs · 50 free credits per new account. If you get a score that looks wrong, I'd like to see it in the comments.