Blog / build-automated-video-transcription-pipeline-nodejs

How to Build an Automated Video Transcription Pipeline in Node.js

Quick answer

The architecture of a video transcription pipeline in Node.js: audio extraction with FFmpeg, a job queue, polling for results, and subtitle output.

2026-08-29 | 7 min read | ReelWords Team

Diagram of a Node.js video transcription pipeline from upload to subtitle file.

A video transcription pipeline in Node.js has four jobs: get audio out of the video, run the slow work off the request thread, wait for the transcription service to finish, and turn the result into a subtitle file. This guide walks through each stage with code, then shows the shorter version where an API accepts the video URL and handles the first three stages for you.

For the caption-rendering side of automation, see our guide to automating your caption pipeline with an API.

The architecture of a video transcription pipeline in Node.js

A pipeline has to solve three engineering problems:

  1. Large files. A multi-gigabyte video cannot be read into memory. Everything has to stream.
  2. Slow processing. Transcription takes longer than an HTTP request should stay open, so the work has to be asynchronous.
  3. Format variety. Video arrives in many containers and codecs. Speech APIs want a small, predictable audio file.

The flow that handles all three:

Upload → Extract audio (FFmpeg) → Queue → Transcription API → Poll for result → Format output (SRT/VTT)

Step 1: Extract audio with FFmpeg

Sending a whole video to a speech API wastes bandwidth and may exceed the API's upload limit. Extract the audio first. FFmpeg must be installed on the server or in the container image.

Calling the ffmpeg binary through child_process keeps the dependency list short:

import { spawn } from 'node:child_process';

export function extractAudio(inputPath, outputPath) {
  return new Promise((resolve, reject) => {
    const ffmpeg = spawn('ffmpeg', [
      '-y',
      '-i', inputPath,
      '-vn',            // drop the video stream
      '-ac', '1',       // mono
      '-ar', '16000',   // 16 kHz is enough for speech
      '-c:a', 'libmp3lame',
      '-q:a', '4',
      outputPath,
    ]);
    ffmpeg.on('error', reject);
    ffmpeg.on('close', (code) =>
      code === 0 ? resolve(outputPath) : reject(new Error(`ffmpeg exited with ${code}`))
    );
  });
}

inputPath can also be an HTTPS URL to a media file, which avoids a separate download step. Our guide to extracting audio from a video URL covers format choices and platform page URLs.

Step 2: Put the work on a queue

The endpoint that receives an upload should not wait for transcription. Create a job record with a processing status, return its ID to the client, and let a background worker do the rest.

Common choices in Node.js:

  • BullMQ with Redis, for retries, concurrency limits, and delayed jobs.
  • Postgres, using a library such as pg-boss or LISTEN/NOTIFY, if you would rather not run Redis.
  • A managed queue such as AWS SQS or Google Cloud Tasks.

Whichever you pick, set a concurrency limit. FFmpeg is CPU-heavy, and running one process per incoming request will exhaust a small server quickly.

Step 3: Send the audio to a transcription API

With a general speech-to-text API the pattern is the same across providers:

  1. Upload the audio file, or give the API a URL to it.
  2. Receive a job ID, or a direct response for short files.
  3. Wait for completion through a webhook if the provider offers one, or by polling.

Providers differ in price, upload limits, and output formats. Our speech-to-text API comparison lists current prices and the pipeline differences that matter for video.

Step 4: Generate subtitles (SRT or VTT)

Speech APIs return JSON with timestamps. Web players need WebVTT, and editors and most platforms accept SRT. If your provider does not return those formats, you write the formatter:

const pad = (n, width = 2) => String(n).padStart(width, '0');

const srtTime = (seconds) => {
  const ms = Math.round(seconds * 1000);
  const h = Math.floor(ms / 3600000);
  const m = Math.floor((ms % 3600000) / 60000);
  const s = Math.floor((ms % 60000) / 1000);
  return `${pad(h)}:${pad(m)}:${pad(s)},${pad(ms % 1000, 3)}`;
};

export const toSrt = (segments) =>
  segments
    .map((seg, i) => `${i + 1}\n${srtTime(seg.start)} --> ${srtTime(seg.end)}\n${seg.text}\n`)
    .join('\n');

The differences between the two formats are covered in SRT vs VTT.

The shorter version: let an API take the video URL

If your videos are reachable at a public URL, including YouTube, TikTok, Instagram, X, and Facebook links, the ReelWords API removes the extraction and formatting stages. You send the URL, poll the job, and download the file. The API does not send webhooks, so polling is the completion signal.

This runs on Node.js 18 or later with no dependencies:

const BASE = 'https://api.reelwords.ai/api/v1';
const headers = { 'x-api-key': process.env.REELWORDS_KEY };

async function request(path, init = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: { ...headers, ...init.headers },
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res;
}

export async function transcribe(videoUrl, { format = 'srt', timeoutMs = 600_000 } = {}) {
  const created = await request('/transcript-jobs', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ url: videoUrl }),
  });
  const { id } = await created.json();

  const deadline = Date.now() + timeoutMs;
  let delay = 2000;
  while (Date.now() < deadline) {
    const job = await (await request(`/transcript-jobs/${id}`)).json();
    if (job.status === 'complete') {
      const file = await request(`/transcript-jobs/${id}/download?format=${format}`);
      return file.text();
    }
    if (job.status === 'failed') {
      throw new Error(`${job.failureReason}: ${job.failureMessage}`);
    }
    await new Promise((resolve) => setTimeout(resolve, delay));
    delay = Math.min(delay * 1.5, 15000);
  }
  throw new Error(`Job ${id} did not finish within ${timeoutMs} ms`);
}

format accepts srt, vtt, txt, and txt_timestamps. A 402 on creation means the plan's allowance is used up. Inside a queue worker, this function replaces steps 1, 3, and 4; you still want the queue from step 2 so that polling does not tie up a web request. The full contract is in the API docs, and the same flow in Python is in our Python transcription tutorial.

Build or integrate?

You should build the full pipeline whenYou can integrate when
Files are private and cannot be exposed at a URLVideos are at public URLs
You need a specific speech model or on-premise processingTranscripts in SRT, VTT, or text are the goal
You already operate FFmpeg and a queueYou would rather not maintain FFmpeg images

See what the API covers on the features page, and plan limits on pricing.

FAQ

Why use Node.js for a transcription pipeline?

The work is mostly I/O: reading files, spawning FFmpeg, and making HTTP requests. Node's non-blocking model handles that well, and the CPU-heavy part runs in the FFmpeg process, not in your event loop.

Can I skip FFmpeg and send the video directly?

Only if the service accepts video or a video URL. General speech APIs usually have upload size limits that a video file exceeds, so extracting audio first is the safer default.

What is the difference between SRT and VTT?

SRT is the older, widely supported format used by editors and most platforms. WebVTT is the web standard for the HTML5 <track> element and supports styling and positioning.

Do I need Redis for the queue?

No. Redis with BullMQ is a common choice, but Postgres-based queues and managed services such as SQS work as well.

Should I use webhooks or polling?

Use webhooks when the provider offers them and you can expose a public endpoint. Otherwise poll with a growing delay and a hard timeout. The ReelWords API is polling-only.

How long does transcription take?

It depends on the provider, the model, and the length of the audio, so measure it for your own files. Design the pipeline so that nothing depends on a fixed duration: always poll or wait with a timeout.

How do I handle failed jobs?

Store the failure reason, mark the job as failed for the user, and retry only errors that can succeed on a second attempt, such as network timeouts. A private or deleted video will fail again.