Why Long Audio Is a Distinct Problem

Every transcription example so far has assumed the audio file fits comfortably within a single API request. Real audio does not cooperate with that assumption: a recorded lecture might run ninety minutes, a customer support call recording might exceed an hour, and a full podcast episode routinely runs well past any single request's file size or duration ceiling. Handling long audio is not a matter of just "sending a bigger file" — it requires splitting the audio into chunks, transcribing each chunk, and reassembling the results in a way that produces a coherent, correctly-timed final transcript.

This lesson also covers the second half of production readiness: what happens when something goes wrong mid-pipeline. A long-running, multi-chunk transcription job has considerably more opportunities to fail partway through than a single short request does, so building reliable retry and failure-recovery logic matters more here than anywhere else in this unit.

Splitting Long Audio into Chunks

Splitting audio requires an audio-processing library, since raw audio files cannot be split at arbitrary byte offsets without corrupting the format (unlike splitting a plain text file). The pydub library is a common, straightforward choice for this in Python.

from pydub import AudioSegment


def split_audio_into_chunks(file_path: str, chunk_duration_seconds: int = 600) -> list[AudioSegment]:
    """
    Splits an audio file into sequential chunks of roughly equal length.
    chunk_duration_seconds defaults to 600 (10 minutes), comfortably under
    typical transcription endpoint duration and size limits.
    """
    audio = AudioSegment.from_file(file_path)
    chunk_length_ms = chunk_duration_seconds * 1000

    chunks = []
    for start_ms in range(0, len(audio), chunk_length_ms):
        chunk = audio[start_ms:start_ms + chunk_length_ms]
        chunks.append(chunk)

    return chunks

AudioSegment.from_file loads the audio file into memory in a format-agnostic way (handling MP3, WAV, and other common formats through the same interface), and len(audio) returns its duration in milliseconds — this is why chunk_duration_seconds is multiplied by 1000 to convert to the same unit before slicing. The range(0, len(audio), chunk_length_ms) loop walks through the audio in fixed-size windows, and Python's slice syntax on an AudioSegment (audio[start_ms:start_ms + chunk_length_ms]) extracts each window as its own independent audio segment. The final chunk will naturally be shorter than the others if the total duration is not an exact multiple of the chunk length, which slicing handles automatically without extra logic — slicing past the end of a sequence in Python simply stops at the end rather than raising an error.

Note: pydub depends on an external audio decoding tool (commonly ffmpeg) being installed and available on the system running this code. It is a third-party library, not part of the OpenAI SDK, and its API and dependency requirements should be confirmed against its current documentation before relying on it in a production pipeline.

Choosing chunk_duration_seconds involves a real trade-off: shorter chunks mean more API calls (more overhead, more chances for a transient failure) but stay safely under any duration or size limit; longer chunks mean fewer calls but risk exceeding a limit if the audio has a higher bitrate than expected. A conservative default like 10 minutes, well under commonly cited limits, is a reasonable starting point that leaves margin for variation in file size per second of audio.

Transcribing Chunks and Reassembling with Correct Timestamps

Each chunk, once transcribed independently, reports timestamps relative to its own start, not the original file. Reassembling a coherent full-length transcript requires adding each chunk's time offset back to its segment timestamps.

import io
from openai import OpenAI

client = OpenAI()


def transcribe_long_audio(file_path: str, chunk_duration_seconds: int = 600):
    chunks = split_audio_into_chunks(file_path, chunk_duration_seconds)
    all_segments = []
    full_text_parts = []

    for index, chunk in enumerate(chunks):
        offset_seconds = index * chunk_duration_seconds

        buffer = io.BytesIO()
        chunk.export(buffer, format="mp3")
        buffer.name = f"chunk_{index}.mp3"
        buffer.seek(0)

        transcript = client.audio.transcriptions.create(
            model="gpt-5.6-terra",
            file=buffer,
            response_format="verbose_json",
            timestamp_granularities=["segment"],
        )

        full_text_parts.append(transcript.text)

        for segment in transcript.segments:
            all_segments.append({
                "start": segment.start + offset_seconds,
                "end": segment.end + offset_seconds,
                "text": segment.text,
            })

    return {
        "text": " ".join(full_text_parts),
        "segments": all_segments,
    }

Several details here matter for correctness. chunk.export(buffer, format="mp3") serializes the in-memory AudioSegment chunk back into MP3 bytes written into an io.BytesIO buffer — this reuses exactly the in-memory buffer pattern from Lesson 3, since each chunk exists only in memory and was never written to its own file on disk. buffer.seek(0) resets the buffer's read position back to the beginning after writing to it; without this, the subsequent create() call would try to read from the buffer's current position (the end, right after writing), and would see no data at all — this is one of the most common and confusing bugs when working with in-memory byte buffers, since the error it produces (empty or invalid file content) gives no obvious hint that a missing seek(0) is the actual cause.

The offset arithmetic — segment.start + offset_seconds — is what makes the reassembled segment list globally consistent: a segment reported as starting at 30.0 seconds within chunk index 2 (with a 600-second chunk duration) is correctly recorded as starting at 1230.0 seconds in the full recording, since offset_seconds for that chunk is 2 * 600 = 1200. Skipping this adjustment is a subtle bug — the individual transcript text would still look correct, but every downstream feature relying on timestamps (subtitle generation from Lesson 4, jump-to-moment navigation) would silently reference the wrong point in the original audio for every chunk after the first.

Handling Failures Mid-Pipeline

A multi-chunk transcription job has many more opportunities to fail than a single-request job: any individual chunk's request can hit a transient network error, a rate limit, or a timeout. Retrying the entire job from scratch after a failure on chunk 40 of 50 wastes significant time and cost. A more resilient approach retries only the failed chunk, with backoff, and preserves progress already made.

import time
from openai import OpenAI, APIError, RateLimitError

client = OpenAI()


def transcribe_chunk_with_retry(buffer, max_retries: int = 3, base_delay: float = 2.0):
    last_error = None

    for attempt in range(max_retries):
        try:
            buffer.seek(0)
            return client.audio.transcriptions.create(
                model="gpt-5.6-terra",
                file=buffer,
                response_format="verbose_json",
                timestamp_granularities=["segment"],
            )
        except RateLimitError as exc:
            last_error = exc
            delay = base_delay * (2 ** attempt)
            time.sleep(delay)
        except APIError as exc:
            last_error = exc
            time.sleep(base_delay)

    raise RuntimeError(f"Chunk transcription failed after {max_retries} attempts") from last_error

This function implements exponential backoff specifically for rate-limit errors: delay = base_delay * (2 ** attempt) doubles the wait time on each successive attempt (2 seconds, then 4, then 8, and so on), which gives a temporarily rate-limited API time to recover rather than immediately hammering it again with an identical request. Other API errors get a flat retry delay instead, since they are less likely to be resolved by a longer wait and more likely to require a genuinely different underlying fix. buffer.seek(0) is called again at the top of each retry attempt, for the same reason explained above — a previous failed read attempt may have left the buffer's position somewhere other than the start.

Critically, this function raises a RuntimeError with the original exception chained via from last_error only after exhausting all retries, rather than either silently swallowing the failure (which would produce a transcript with a missing chunk and no indication anything went wrong) or immediately propagating the very first transient error (which would cause the entire long job to fail unnecessarily for what might have been a brief, recoverable network hiccup).

Persisting Progress for Resumability

For very long jobs (an hour or more, meaning dozens of chunks), saving intermediate results as they complete — rather than holding everything in memory until the very end — allows a job to resume from where it left off if the overall process is interrupted, rather than restarting from chunk one.

import json
from pathlib import Path


def save_progress(job_id: str, chunk_index: int, transcript_data: dict, progress_dir: str = "transcription_progress"):
    directory = Path(progress_dir) / job_id
    directory.mkdir(parents=True, exist_ok=True)
    chunk_file = directory / f"chunk_{chunk_index:04d}.json"
    chunk_file.write_text(json.dumps(transcript_data))


def load_completed_chunks(job_id: str, progress_dir: str = "transcription_progress") -> dict[int, dict]:
    directory = Path(progress_dir) / job_id
    if not directory.exists():
        return {}

    completed = {}
    for chunk_file in directory.glob("chunk_*.json"):
        index = int(chunk_file.stem.split("_")[1])
        completed[index] = json.loads(chunk_file.read_text())
    return completed

save_progress writes each completed chunk's transcript data to its own JSON file, named with a zero-padded index (chunk_0000.json, chunk_0001.json, and so on) so files sort in the correct order when listed. load_completed_chunks reads back whatever chunk files already exist for a given job_id at the start of a run, returning a dictionary keyed by chunk index — a resumable version of the long-audio transcription loop would check this dictionary before processing each chunk, skipping any index already present, and only calling the API for chunks that are genuinely missing. This pattern — checkpointing partial results to disk, keyed by a stable identifier — is a general and reusable technique for any long-running, multi-step job, not specific to audio transcription.

Common Mistakes

Forgetting to reset a buffer's read position with seek(0) after writing to it or after a failed read attempt, which causes the API to receive an empty or truncated file with no obvious error message pointing to the actual cause. This is one of the most common and hardest-to-diagnose mistakes when working with in-memory audio buffers.

Forgetting to add each chunk's time offset back into its segment timestamps, which causes every chunk after the first to report timestamps relative to its own start rather than the original recording — silently breaking any downstream feature (subtitles, jump-to-moment navigation) that depends on accurate absolute timing.

Retrying an entire long-audio job from the beginning after a single chunk fails, which wastes significant time and API cost for large files. Retry and checkpoint at the chunk level, not the whole-job level.

Best Practices

Choose a conservative chunk duration with real margin below the endpoint's actual limits, since audio bitrate varies and a chunk that is safely under the duration limit could still exceed a file size limit depending on encoding quality.

Implement exponential backoff specifically for rate-limit errors, and a shorter flat retry delay for other transient errors, rather than treating every failure identically.

Checkpoint progress for any job long enough that a full restart would be genuinely costly, using a simple, inspectable format like one JSON file per completed chunk, so a resumable job can pick up exactly where it left off after an interruption.