@decrackle/sdk

Official Node.js & browser SDK for the Decrackle Audio AI Platform

Documentation · Dashboard · npm

Features

• 🎙 Speech-to-Text — batch and real-time streaming transcription
• 🔇 Audio Denoising — AI-powered noise removal
• 💾 Storage — quota and usage management
• ⚡ TypeScript-first — full types, zero runtime dependencies
• 🔁 Production-ready — automatic retries, timeouts, cancellation, typed errors

Installation

npm install @decrackle/sdk

Requires Node.js 18+. Works in modern browsers too.

Quick Start

import { Decrackle } from '@decrackle/sdk';
import { readFileSync } from 'fs';

const client = new Decrackle({ apiKey: 'decrackle_sdk_...' });

const audio = readFileSync('./recording.mp3');

// Transcribe
const result = await client.asr.transcribe(audio, { language: 'en' });
console.log(result.transcriptionText);

// Denoise
const denoised = await client.denoise.process(audio);
console.log('Download:', denoised.outputUrl);

Get your API key from the Decrackle dashboard.

Authentication

// Pass directly
const client = new Decrackle({ apiKey: 'decrackle_sdk_...' });

// Or via environment variable — no code change needed
// DECRACKLE_API_KEY=decrackle_sdk_...
const client = new Decrackle();

Speech to Text (ASR)

Batch transcription

const result = await client.asr.transcribe(audioBuffer, {
  language: 'en',        // ISO code or full name — omit for auto-detect
  includeScoring: true,  // MOS quality score (Professional plan)
});

console.log(result.transcriptionText);
console.log(result.detectedLanguage);
console.log(result.qualityScore);
console.log(result.audioMetadata?.durationSeconds);

Supported formats: MP3 · WAV · FLAC · OGG · M4A · AAC

Supported languages: English, German, Italian, Spanish, French, Hindi, Japanese, Arabic

Streaming transcription

for await (const event of client.asr.transcribeStream(audioBuffer, { language: 'en' })) {
  if (event.type === 'chunk') {
    process.stdout.write(event.text);
  }
  if (event.type === 'complete') {
    console.log('\nJob ID:', event.jobId);
  }
}

Job management

// List jobs
const page = await client.asr.jobs.list({ status: 'completed', limit: 10 });

// Get a job
const job = await client.asr.jobs.get('job_abc123');

// Delete a job and its files
await client.asr.jobs.delete('job_abc123');

// Refresh expired download URLs
const { inputUrl } = await client.asr.jobs.refreshUrls('job_abc123');

Audio Denoising

const result = await client.denoise.process(audioBuffer);

console.log('Output URL:', result.outputUrl);
console.log('Input URL:', result.inputUrl);
console.log('Processing time:', result.processingTimeMs, 'ms');

Output format

Choose the storage format for the cleaned file (availability depends on your plan; the format is permanent once the job is created):

// See what your plan allows
const { formats, defaultFormat } = await client.denoise.formats();

// Store as FLAC instead of the default
const result = await client.denoise.process(audioBuffer, { outputFormat: 'flac' });
console.log(result.outputFormat); // 'flac'

Job management

const page  = await client.denoise.jobs.list({ limit: 20 });
const job   = await client.denoise.jobs.get('job_xyz');
const retry = await client.denoise.jobs.retry('job_xyz');   // re-run failed job
await client.denoise.jobs.delete('job_xyz');
const { outputUrl } = await client.denoise.jobs.refreshUrls('job_xyz');

Storage

const info = await client.storage.info();

console.log(`${info.usedBytes} / ${info.limitBytes ?? '∞'} bytes`);

if (info.usagePercent && info.usagePercent > 90) {
  console.warn('Storage nearly full — consider deleting old jobs');
}

File Input

The SDK accepts audio in any of these forms:

import { readFileSync } from 'fs';

// Node.js Buffer
await client.asr.transcribe(readFileSync('./audio.mp3'));

// Named file with explicit MIME type
await client.asr.transcribe({
  data: readFileSync('./audio.wav'),
  name: 'recording.wav',
  type: 'audio/wav',
});

// Browser File / Blob
await client.asr.transcribe(fileInputElement.files[0]);

Error Handling

All errors extend DecrackleError with a machine-readable code.

import {
  DecrackleAuthError,
  DecrackleFileTooLargeError,
  DecrackleStorageQuotaError,
  DecrackleAudioTooLongError,
  DecrackleMonthlyLimitError,
  DecrackleValidationError,
  DecracklePermissionError,
  DecrackleRateLimitError,
  DecrackleServiceUnavailableError,
} from '@decrackle/sdk';

try {
  await client.asr.transcribe(audio);
} catch (err) {
  if (err instanceof DecrackleAuthError) {
    console.error('Invalid or missing API key');

  } else if (err instanceof DecrackleFileTooLargeError) {
    console.error('File exceeds your plan limit (Free: 10 MB · Professional: 100 MB)');

  } else if (err instanceof DecrackleStorageQuotaError) {
    console.error('Storage quota full — delete old jobs or upgrade');

  } else if (err instanceof DecrackleAudioTooLongError) {
    console.error('Audio too long for your plan (Free: 5 min · Professional: 120 min)');

  } else if (err instanceof DecrackleMonthlyLimitError) {
    console.error('Monthly processing limit reached');

  } else if (err instanceof DecracklePermissionError) {
    console.error('Feature not available on your plan');

  } else if (err instanceof DecrackleRateLimitError) {
    console.error('Rate limited. Retry after:', err.retryAfter, 'ms');

  } else if (err instanceof DecrackleServiceUnavailableError) {
    console.error('Service temporarily unavailable');
  }
}

Error reference

| Class | Status | Code | |---|---|---| | DecrackleAuthError | 401 | UNAUTHORIZED | | DecracklePermissionError | 403 | FEATURE_NOT_AVAILABLE etc. | | DecrackleNotFoundError | 404 | JOB_NOT_FOUND etc. | | DecrackleFileTooLargeError | 413 | FILE_TOO_LARGE | | DecrackleStorageQuotaError | 413 | STORAGE_QUOTA_EXCEEDED | | DecrackleAudioTooLongError | 400 | DURATION_TOO_LONG | | DecrackleMonthlyLimitError | 429 | MONTHLY_LIMIT_EXCEEDED | | DecrackleRateLimitError | 429 | RATE_LIMIT_EXCEEDED | | DecrackleServiceUnavailableError | 503 | MODEL_UNAVAILABLE etc. | | DecrackleNetworkError | — | NETWORK_ERROR | | DecrackleTimeoutError | — | REQUEST_TIMEOUT |

Plan Limits

| | Free | Professional | |---|---|---| | Max file size | 10 MB | 100 MB | | Total storage | 10 MB | 100 MB | | ASR max duration | 5 min | 120 min | | Denoise max duration | 10 min | Unlimited | | Streaming transcription | ✅ | ✅ | | Quality scoring | ✅ | ✅ |

Configuration

const client = new Decrackle({
  apiKey:     'decrackle_sdk_...',
  baseURL:    'https://api.decrackle.io', // override for staging/self-hosted
  timeout:    30_000,                     // default timeout in ms
  maxRetries: 2,                          // retries on 5xx / network errors
  fetch:      customFetch,                // custom fetch implementation
});

Per-request options

const controller = new AbortController();
setTimeout(() => controller.abort(), 10_000);

await client.asr.transcribe(audio, { language: 'en' }, {
  signal:     controller.signal,  // cancellation
  timeout:    60_000,             // override timeout for this call
  maxRetries: 0,                  // disable retries for this call
});

TypeScript

Written in TypeScript. Ships .d.ts files — no @types/ package needed.

import type {
  TranscriptionResult,
  TranscriptionStreamEvent,
  DenoisingResult,
  DenoisingJob,
  OutputFormat,
  AvailableFormats,
  StorageInfo,
  PaginatedList,
  FileInput,
} from '@decrackle/sdk';

License

Apache-2.0 © Decrackle