npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@hoanghong/speaking-core

v0.7.7

Published

TypeScript SDK for speech transcription, audio upload and versioned local pronunciation assessment with typed overall and component scores.

Readme

@hoanghong/speaking-core

SDK 0.7.7 supports local-accuracy-prosody-v2: omission-aware Accuracy, configurable Accuracy/Prosody weights (default 65/35), explicit Accuracy-only fallback, and the server's weights, components, and excluded_components. Legacy v1 responses remain supported; v1 examples below describe older servers.

TypeScript SDK for custom speaking interfaces: realtime transcription, audio upload and US English pronunciation diagnostics. Models run on the service. The SDK manages connections and short-lived sessions; no service URL or service token is needed. MIT license.

Install from npm

npm install @hoanghong/[email protected]

Install the supplied version 0.7.7 archive

Copy the tarball from the release ZIP into your application's vendor directory:

npm install ./vendor/hoanghong-speaking-core-0.7.7.tgz

These instructions use the supplied archive and do not assume registry publication. Angular applications may use @hoanghong/speaking-angular; Flutter applications may use fsel_speaking.

Assess pronunciation from a file

Ask the learner to read the exact reference passage. Pass a selected File or recorded Blob to assessAudio. Transcription alone does not assess pronunciation.

import {
  createSpeakingService, PronunciationClient, PronunciationAssessment, SpeakingError,
} from '@hoanghong/speaking-core';

const config = createSpeakingService();
// If FSEL supplied an application key, use instead:
// const config = createSpeakingService({ appKey: 'YOUR_APP_KEY' });
const pronunciation = new PronunciationClient(config.pronunciation);

export async function assessPronunciation(
  file: File,
  referenceText: string,
  signal?: AbortSignal,
): Promise<PronunciationAssessment> {
  try {
    return await pronunciation.assessAudio(file, {
      referenceText,
      filename: file.name,
      signal,
    });
  } catch (error) {
    if (error instanceof SpeakingError) {
      console.error(error.code, error.status, error.message);
    }
    throw error; // Let the UI display the error and offer a deliberate retry.
  }
}

export function describeOverall(result: PronunciationAssessment): string {
  const value = result.overall;
  return value?.status === 'estimated' && value.score != null
    ? `${value.score.toFixed(1)} / ${value.scale} (local estimate)`
    : value?.reason ?? 'Unavailable: upgrade the server if needed';
}

export function describeAccuracy(result: PronunciationAssessment): string {
  const accuracy = result.breakdown?.accuracy;
  console.log(result.comparisons, result.warnings);
  return accuracy?.status === 'estimated' && accuracy.score != null
    ? `${accuracy.score.toFixed(1)} / 100 (estimate)`
    : 'Unavailable';
}

In an async file-selection/button handler, call assessPronunciation(file, 'The cat is sitting on the mat.', controller.signal), then describeAccuracy(result). Create controller with new AbortController(); call controller.abort() when cancelling or leaving the screen. Keep a loading state, disable duplicate submissions and catch errors. Cancellation does not refund quota or guarantee that server inference stops.

For an explicit single-word pronunciation, pass expectedPhonemes: ['k', 'æ', 't'] with referenceText: 'cat'. Each entry must be a complete model vocabulary token. Do not split IPA into characters, include enclosing slashes or reuse these tokens for a different passage. Normally omit expectedPhonemes for sentences; server-side text-to-phoneme support must be installed.

Pronunciation inputs and results

Only en-US pronunciation is supported, independently of transcription language. Audio must be nonempty, at most 120 seconds and 25 MiB. Reference text must contain 1–4096 characters. The service validates duration and supported formats; WAV PCM16 mono at 16 kHz is suitable. The default assessment request timeout is 11 minutes. Each assessment obtains its own session and consumes quota; there is no automatic retry.

| Result field | Meaning | | --- | --- | | overall | Versioned overall local score, status, scale, formula, components and availability reason | | reference_text, expected_phonemes | Passage and expected model tokens | | observed_phonemes | Recognized tokens with approximate start/end seconds | | comparisons | match/substitution/deletion/insertion; missing sounds can have null times | | phoneme_similarity, phoneme_error_rate | Edit-based similarity and error rate, not calibrated grades | | breakdown | Optional criteria, phoneme error counts, acoustic pauses and limitations | | acoustic_frames, psd_frequencies_hz | Formants, pitch, intensity and spectral measurements | | warnings, calibrated, timing_method | Interpretation limits; calibration is false and timing is approximate |

Older services may omit overall and breakdown or return null. Show unavailable criteria as "Unavailable", never zero. Display warnings, criterion method/reason and breakdown.limitations. Error counts refer to phonemes, not words.

Accuracy = 100M/(M+S+I); completeness = 100(N-D)/N, where M/S/D/I mean matches/substitutions/omissions/insertions and N is reference token count. Substitutions count as covered for completeness. Similarity = 100*max(0, 1-(S+D+I)/N), so it differs from accuracy. Fluency is an energy-continuity proxy and can be inflated by noise. Prosody provides pitch measurements without a score. Overall pronunciation is the harmonic mean of Accuracy and Completeness. Vocabulary, grammar and topic scores are unavailable. These estimates are not calibrated educational grades, Azure scores or pass/fail decisions.

Realtime transcription and recorded audio

import {
  createSpeakingService, RealtimeSpeakingClient, SpeakingMicrophone,
} from '@hoanghong/speaking-core';

const config = createSpeakingService();
const client = new RealtimeSpeakingClient(config.realtime);
const microphone = new SpeakingMicrophone(client, config.microphone);
const unsubscribe = client.onEvent(event => {
  if (event.type === 'captureStarted') console.log('Microphone is recording; you can speak now.');
  if (event.type === 'partial') console.log(event.text);
  if (event.type === 'clientError') console.error(event.error);
});

// Call from explicit user actions; catch failures in the UI.
export async function start() { await microphone.start({ language: 'en' }); }
export async function stop() {
  const result = await microphone.stop();
  return { text: result.result?.text ?? '', audio: result.audio };
}
export async function cancel() { await microphone.cancel(); }
export async function dispose() { unsubscribe(); await microphone.dispose(); }

The returned audio is a WAV File, PCM16 mono at 16 kHz, including final buffered samples. Pass it to the pronunciation helper with the passage for a separate assessment. Recording/transcription and pronunciation each create a session. Realtime supports 300 seconds, but assessed recordings must stay within the pronunciation limit of 120 seconds.

captureStarted means local microphone capture is active, including while the server is connecting. start() still resolves when the transport is ready. Startup PCM is bounded by maxQueuedBytes (10 seconds by default); overflow fails explicitly. You can call microphone.stop() during connection: capture stops immediately and finalization waits for buffered audio to reach the server.

Microphone capture requires HTTPS or localhost, getUserMedia and AudioWorklet. The worklet loads automatically. Dispose when unmounting. For playback/download, create an object URL and revoke it when replacing audio or leaving. Use FormData for storage uploads; do not serialize audio into JSON.

Upload for transcription

import { BatchSpeakingClient, createSpeakingService } from '@hoanghong/speaking-core';

export async function transcribe(file: File) {
  if (!file.size || file.size > 25 * 1024 * 1024) {
    throw new Error('Select nonempty audio of at most 25 MiB.');
  }
  const batch = new BatchSpeakingClient(createSpeakingService().batch);
  let job = await batch.submitAudio(file, 'en', crypto.randomUUID(), 'short_answer', file.name);
  const deadline = Date.now() + 600_000;
  while (!['succeeded', 'no_speech', 'failed', 'cancelled'].includes(job.status)) {
    if (Date.now() > deadline) throw new Error('Transcription timed out.');
    await new Promise(resolve => setTimeout(resolve, 1500));
    job = await batch.getResult(job.job_id);
  }
  if (job.error) throw new Error(job.error.message);
  if (job.status === 'cancelled') throw new Error('Transcription was cancelled.');
  return { text: job.result?.text ?? '', audio: file };
}

Retain the batch client for polling/cancellation. Each public batch configuration owns one job capability at a time; use separate clients/configurations for concurrent jobs. Audio is not automatically stored permanently.

Application keys and errors

Use createSpeakingService({ appKey: 'YOUR_APP_KEY' }) for an application key supplied by FSEL. It is a visible application identifier, not an administrative credential. Never embed service credentials. Without a key, the basic anonymous quota applies. Invalid/disabled keys do not fall back to anonymous access.

Transcription languages: en/ja/ko/zh/vi. Basic quota defaults to 5 sessions per IP/day and 100 per instance/day (UTC), subject to operator changes. Sessions count even when processing fails. Realtime PCM buffering is approximately 9.6 MB maximum. Network/CSP must permit SDK connections and worklet loading.

Handle SpeakingError.code/status/message: INVALID_REFERENCE, INVALID_AUDIO, INVALID_APP_KEY/401, QUOTA_EXCEEDED/429, unsupported audio/415, validation/422, missing functionality/404 and unavailable model/service/503. Cancellation and timeouts also reject. Do not automatically retry or replay audio. Installing the library does not deploy or verify service/model readiness.

Overall pronunciation output (0.7.7)

Use result.overall?.score for the overall chart. It is a local estimate, the harmonic mean of unrounded Accuracy and Completeness: 2*A*C/(A+C), or 0 if A+C=0. Fluency and Prosody are excluded. This is not an Azure or calibrated educational grade. phoneme_similarity is a separate legacy edit-distance diagnostic and can be zero while the overall score is positive.

The overall object includes version=local-accuracy-completeness-v1, scale=100, calibrated=false, status, method, reason, components and excluded_components (Flutter: excludedComponents). Render null/unavailable scores as unavailable; preserve valid zero values. An older server can omit overall; the SDK never computes a replacement score. breakdown.pronunciation mirrors the overall criterion for compatibility. The server must be upgraded as well as the SDK.

{"overall":{"score":50,"status":"estimated","method":"accuracy_completeness_hmean: 2*A*C/(A+C); zero if A+C=0","reason":null,"version":"local-accuracy-completeness-v1","scale":100,"calibrated":false,"components":["accuracy","completeness"],"excluded_components":["fluency","prosody"]}}

Dictionary accent comparison (0.7.0)

New servers compare the same recording against pinned CMUdict (US) and Britfone (GB) references. accent_scores reports both results; selected_accent identifies the higher overall score, with US first on exact ties. Top-level scores and comparisons belong to that selection. Missing dictionary coverage is unavailable, never zero-filled. Explicit expected phonemes bypass automatic comparison. Unsupported references retain the legacy eSpeak fallback, without claiming a dictionary accent match. These are uncalibrated diagnostics, not accent identification or educational grades.

Service fixes in 0.7.1

Application-key sessions use the application daily and per-IP limits independently of anonymous public quotas. Short English utterances receive additional decoder context on the updated service. These fixes are server-side: installing this package alone does not deploy them. Vietnamese recognition accuracy remains model-dependent.

Server grading policy (0.7.2)

The updated server adds an optional grading decision without changing overall.score. By default, references with at most five phonemes pass only above 60%; longer references pass only above 75%. Exactly 60% or 75% does not pass the corresponding rule. CMS administrators can change the split and both thresholds. Always use the returned decision and rule snapshot; do not hardcode thresholds in your application. Counts refer to normalized reference phonemes, including omitted sounds, excluding learner insertions, not letters or syllables.

Older servers may omit grading. A null passed means no decision is available; it must not be displayed as a failed attempt. These are configurable acceptance rules for uncalibrated diagnostics, not a change to acoustic or prosody scoring.

// assessment is the result of pronunciation.assessAudio(...).
const grading = assessment.grading;
const outcome = grading?.passed == null
  ? 'Unavailable'
  : grading.passed ? 'Pass' : 'Not passed';
console.log(outcome, grading?.reference_phoneme_count, grading?.threshold);