How to Split Video into Segments with FFmpeg (CLI + API)

set_timestamps 1
-segment_list manifest.json
-segment_list_flags +live
-segment_format_options movflags=+faststart
batch_%04d.mp4

**Architecture Decisions:**
*   `-reset_timestamps 1`: Resets the presentation timestamp (PTS) of each segment to zero. Without this, media players interpret the segment timestamps relative to the source, causing seek bars to display incorrect positions and potentially failing to play the file.
*   `-segment_list_flags +live`: Optimizes the manifest for streaming scenarios by keeping the file open and appending entries as segments are created, rather than writing the full list only after completion.
*   `-segment_format_options movflags=+faststart`: Reorders the MP4 atom structure so metadata appears at the beginning of the file. This enables progressive playback and faster seeking in web browsers.
*   `batch_%04d.mp4`: The `%04d` pattern is mandatory. FFmpeg increments this integer for each new segment. Omitting this causes the muxer to overwrite the same file repeatedly.

#### 2. Handling Keyframe Alignment

When precision is required, you must force keyframe insertion. This requires re-encoding the video stream to insert I-frames at exact intervals.

**Implementation:**

```bash
ffmpeg -i source_feed.mp4 \
  -c:v libx264 \
  -g 50 \
  -keyint_min 50 \
  -sc_threshold 0 \
  -crf 23 \
  -f segment \
  -segment_time 10 \
  -reset_timestamps 1 \
  precise_%03d.mp4

Rationale:

• -g 50: Sets the GOP size to 50 frames. At 25fps, this forces a keyframe every 2 seconds.
• -keyint_min 50: Ensures the minimum interval matches the maximum, preventing variable GOP lengths.
• -sc_threshold 0: Disables scene change detection, ensuring keyframes are placed strictly based on the frame count rather than visual content changes.
• Trade-off: This approach increases processing time by 20x to 50x depending on hardware and CRF settings. Use only when frame-accurate cuts are non-negotiable.

3. Distributed API Orchestration

For high-volume pipelines, submitting independent extraction jobs to a cloud API allows parallel processing. This pattern uses -ss (seek) and -t (duration) to extract specific windows from the source.

TypeScript Implementation:

interface TranscodeOption {
  option: string;
  argument: string;
}

interface TranscodePayload {
  inputs: { url: string }[];
  outputFormat: string;
  options: TranscodeOption[];
}

class VideoSegmenter {
  private apiKey: string;
  private baseUrl: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.ffmpeg-micro.com/v1';
  }

  async submitSegment(
    sourceUrl: string,
    offsetSeconds: number,
    durationSeconds: number
  ): Promise<string> {
    const payload: TranscodePayload = {
      inputs: [{ url: sourceUrl }],
      outputFormat: 'mp4',
      options: [
        { option: '-ss', argument: String(offsetSeconds) },
        { option: '-t', argument: String(durationSeconds) },
        { option: '-c', argument: 'copy' }
      ]
    };

    const response = await fetch(`${this.baseUrl}/transcodes`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.statusText}`);
    }

    const data = await response.json();
    return data.id;
  }

  async splitVideo(
    sourceUrl: string,
    totalDuration: number,
    segmentLength: number
  ): Promise<string[]> {
    const jobIds: string[] = [];
    const promises: Promise<string>[] = [];

    for (let offset = 0; offset < totalDuration; offset += segmentLength) {
      const remaining = totalDuration - offset;
      const duration = Math.min(segmentLength, remaining);
      
      promises.push(
        this.submitSegment(sourceUrl, offset, duration)
      );
    }

    const results = await Promise.all(promises);
    return results;
  }
}

// Usage
const segmenter = new VideoSegmenter('YOUR_API_KEY');
segmenter.splitVideo('https://storage.example.com/long_video.mp4', 600, 30)
  .then(ids => console.log('Submitted segments:', ids))
  .catch(err => console.error('Pipeline failed:', err));

Architecture Decisions:

• Parallel Submission: The splitVideo method creates promises for all segments and resolves them concurrently. This maximizes throughput by utilizing the API's concurrent job limits.
• Boundary Handling: The Math.min logic ensures the final segment does not exceed the total duration, preventing API errors on the last chunk.
• Stream Copy: Using -c copy in the API options maintains speed. Since each job extracts a specific window, the keyframe alignment variance is isolated to the start of each segment, which is often acceptable for clipping workflows.

Pitfall Guide

1. Timestamp Corruption

   • Explanation: Omitting -reset_timestamps 1 causes segments to retain source timestamps. Players may show a 1-hour seek bar for a 30-second clip, and some decoders will reject the file.
   • Fix: Always include -reset_timestamps 1 in segment muxer commands.

2. Container Format Incompatibility

   • Explanation: MP4 files require specific atom ordering for segmentation to work reliably. Segmenting an MP4 without +faststart can result in files that are unplayable until the entire file is downloaded.
   • Fix: Use -segment_format_options movflags=+faststart for MP4, or switch to MKV/TS containers which support segmentation natively without reordering.

3. Audio Desynchronization

   • Explanation: Stream copying audio can introduce sync drift or audio pops at segment boundaries due to codec delay and padding differences.
   • Fix: Re-encode the audio track while copying video: -c:v copy -c:a aac. This adds minimal overhead compared to full re-encoding and resolves sync issues.

4. Manifest File Bloat

   • Explanation: Generating a CSV or JSON manifest for a video with thousands of segments can consume excessive memory and disk I/O.
   • Fix: Use -segment_list_type flat for simple filename lists, or process videos in smaller batches to keep manifest sizes manageable.

5. Keyframe Misalignment Assumptions

   • Explanation: Assuming -segment_time produces exact durations with -c copy. If the GOP is large, segments will vary significantly.
   • Fix: Analyze the source GOP size using ffprobe. If precision is required, force keyframes via re-encoding or accept the variance in your pipeline logic.

6. Clock Time vs. Duration Confusion

   • Explanation: Using -segment_time when the requirement is to split at specific clock times (e.g., every hour on the hour).
   • Fix: Use -segment_atclocktime 1 to align segments with wall-clock time rather than relative duration.

7. API Polling Timeouts

   • Explanation: Implementing aggressive polling loops for API job status can lead to rate limiting or unnecessary API costs.
   • Fix: Implement exponential backoff in your polling logic. Start with a 1-second interval and double the delay up to a maximum cap.

Production Bundle

Action Checklist

• Verify source GOP size using ffprobe before selecting stream copy vs. re-encode strategy.
• Include -reset_timestamps 1 in all segment muxer commands to ensure independent playback.
• Validate output filename patterns contain %d or %03d to prevent file overwrites.
• Test audio sync on segment boundaries; switch to -c:a aac if drift is detected.
• Configure -segment_list to generate manifests for pipeline tracking and verification.
• Use -segment_format_options movflags=+faststart for MP4 outputs intended for web delivery.
• Implement exponential backoff for API job polling to avoid rate limits.
• For videos exceeding 1 hour, prefer distributed API jobs over local muxer execution to prevent timeouts.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Social Media Clipping	Stream Copy Muxer	Speed is critical; keyframe variance is acceptable.	Low compute cost.
HLS Streaming Origin	Stream Copy Muxer + Manifest	Low latency; manifest enables playlist generation.	Low compute; storage for manifest.
Legal/Forensic Extraction	Re-encode with Forced Keyframes	Frame accuracy is mandatory.	High compute cost; longer processing time.
High-Volume CMS Ingestion	API Parallel Jobs	Throughput scales with concurrency; no local infra.	API usage fees; zero infra maintenance.
Hourly Broadcast Splits	Segment Muxer with Clock Time	Aligns segments to wall-clock boundaries.	Low compute; requires precise scheduling.

Configuration Template

Copy this template for a production-ready local segmentation command. Adjust variables as needed.

#!/bin/bash

INPUT_FILE="${1:-input.mp4}"
SEGMENT_DURATION="${2:-30}"
OUTPUT_PREFIX="${3:-segment}"
MANIFEST_FILE="${4:-manifest.json}"

ffmpeg -i "$INPUT_FILE" \
  -c copy \
  -f segment \
  -segment_time "$SEGMENT_DURATION" \
  -reset_timestamps 1 \
  -segment_list "$MANIFEST_FILE" \
  -segment_list_flags +live \
  -segment_format_options movflags=+faststart \
  "${OUTPUT_PREFIX}_%04d.mp4"

if [ $? -eq 0 ]; then
  echo "Segmentation complete. Manifest: $MANIFEST_FILE"
else
  echo "Segmentation failed."
  exit 1
fi

Quick Start Guide

1. Install FFmpeg: Ensure FFmpeg 7.x or later is installed and accessible in your PATH.
2. Run Basic Segmentation: Execute ffmpeg -i video.mp4 -c copy -f segment -segment_time 10 -reset_timestamps 1 clip_%03d.mp4 to generate 10-second clips.
3. Verify Output: Check that files clip_000.mp4, clip_001.mp4, etc., are created and play independently with correct seek behavior.
4. Generate Manifest: Add -segment_list manifest.csv -segment_list_type csv to the command to produce a tracking file with segment durations.
5. Test API Parallelism: Use the TypeScript VideoSegmenter class to submit multiple segments concurrently, monitoring job IDs for status polling.