mpeg

mpeg is a small Dart wrapper around the system ffmpeg and ffprobe binaries. It uses dart:io processes directly, so it works well in server-side Dart apps, Docker containers, and macOS environments where FFmpeg is installed on the host.

Features

• Check whether ffmpeg and ffprobe are available with MpegClient.isSupported()
• Read parsed ffmpeg and ffprobe version information
• Run ffmpeg and ffprobe commands with Process.run or Process.start
• Decode ffprobe JSON output with probeJson()
• Pull out parsed format metadata, streams, duration, bitrate, and primary video/audio streams
• Parse ffmpeg -formats / ffprobe -formats output into structured MpegFormat objects
• Resolve common supported video file extensions from the detected format list for both input and output support
• Use low-friction helpers for generic transcode, remux, and still-frame extraction
• Configure executable paths, base arguments, environment variables, and shell behavior

Installation

Add the package:

dart pub add mpeg

You also need FFmpeg installed on the machine that runs your Dart code.

Docker Linux

For Debian/Ubuntu-based Docker images, install FFmpeg like this:

RUN apt-get update && apt-get install -y ffmpeg

That installs both ffmpeg and ffprobe.

macOS

Install FFmpeg with Homebrew:

brew install ffmpeg

You can verify the install with:

ffmpeg -version
ffprobe -version

Usage

Check whether FFmpeg is available

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  bool supported = await MpegClient.isSupported();
  if (!supported) {
    throw StateError('ffmpeg/ffprobe are not installed or not on PATH.');
  }
}

Inspect supported formats

getFormats() parses the real -formats output from ffprobe first, then falls back to ffmpeg if needed.

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  MpegClient client = MpegClient();

  List<MpegFormat> formats = await client.getFormats();
  for (MpegFormat format in formats.take(5)) {
    print(
      '${format.primaryName}: demux=${format.canDemux}, mux=${format.canMux}, '
      'device=${format.isDevice}',
    );
  }

  List<String> inputExtensions =
      await client.getSupportedVideoInputExtensions();
  List<String> outputExtensions =
      await client.getSupportedVideoOutputExtensions();
  print('Inputs: $inputExtensions');
  print('Outputs: $outputExtensions');
}

getSupportedVideoExtensions() resolves common video file extensions from the parsed format names. The input/output convenience methods are useful when you want to answer questions like "which video extensions can this machine decode?" versus "which containers can it mux?"

Read ffmpeg version information

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  MpegClient client = MpegClient();

  MpegVersionInfo ffmpegVersion = await client.getFfmpegVersionInfo();
  MpegVersionInfo ffprobeVersion = await client.getFfprobeVersionInfo();

  print(ffmpegVersion.version);
  print(ffprobeVersion.configurationLine);
}

Probe targeted metadata helpers

If you do not want to manually walk the full JSON payload, the client exposes small convenience helpers:

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  MpegClient client = MpegClient();

  Duration? duration = await client.probeDuration(inputPath: 'output.mp4');
  int? bitRate = await client.probeBitRate(inputPath: 'output.mp4');
  Map<String, dynamic>? videoStream = await client.probePrimaryVideoStream(
    inputPath: 'output.mp4',
  );

  print(duration);
  print(bitRate);
  print(videoStream?['width']);
}

Transcode a file and probe the result

import 'dart:convert';
import 'dart:io';

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  MpegClient client = MpegClient();
  File inputFile = File('input.mov');
  File outputFile = File('output.mp4');

  ProcessResult result = await client.runFfmpeg([
    '-y',
    '-i',
    inputFile.path,
    '-vf',
    'scale=1280:720',
    '-c:v',
    'libx264',
    '-pix_fmt',
    'yuv420p',
    '-movflags',
    '+faststart',
    outputFile.path,
  ]);

  if (result.exitCode != 0) {
    stderr.writeln(result.stderr);
    return;
  }

  Map<String, dynamic> metadata = await client.probeJson(
    inputPath: outputFile.path,
  );
  print(const JsonEncoder.withIndent('  ').convert(metadata));
}

Use the convenience operations

These are just thin wrappers around common ffmpeg command shapes, so you still control the real ffmpeg flags.

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  MpegClient client = MpegClient();

  await client.transcode(
    inputPath: 'input.mov',
    outputPath: 'output.mp4',
    ffmpegArguments: [
      '-vf',
      'scale=1280:720',
      '-c:v',
      'libx264',
      '-pix_fmt',
      'yuv420p',
    ],
  );

  await client.remux(
    inputPath: 'input.mov',
    outputPath: 'faststart.mp4',
    ffmpegArguments: ['-movflags', '+faststart'],
  );

  await client.extractFrame(
    inputPath: 'input.mov',
    outputPath: 'thumbnail.png',
    position: const Duration(milliseconds: 500),
    width: 320,
    height: 180,
  );
}

Stream process output with Process.start

If you want progress events or long-running streaming output, use startFfmpeg() or startFfprobe():

import 'dart:convert';
import 'dart:io';

import 'package:mpeg/mpeg.dart';

Future<void> main() async {
  MpegClient client = MpegClient();
  Process process = await client.startFfmpeg(
    arguments: [
      '-i',
      'input.mov',
      '-progress',
      'pipe:2',
      'output.mp4',
    ],
  );

  await for (String line in process.stderr
      .transform(utf8.decoder)
      .transform(const LineSplitter())) {
    print(line);
  }

  int exitCode = await process.exitCode;
  print('ffmpeg exited with $exitCode');
}

Configuration

You can point the client at custom binary paths or wrapper commands:

import 'package:mpeg/mpeg.dart';

MpegClient client = MpegClient(
  ffmpegExecutable: '/usr/local/bin/ffmpeg',
  ffprobeExecutable: '/usr/local/bin/ffprobe',
  workingDirectory: '/tmp',
  environment: {'FFREPORT': 'file=ffreport.log:level=32'},
);

API Overview

• MpegClient.isSupported() checks whether ffmpeg and optionally ffprobe can be started
• runFfmpeg() and runFfprobe() wrap Process.run
• startFfmpeg() and startFfprobe() wrap Process.start
• probeJson() returns decoded ffprobe JSON
• probeFormat(), probeStreams(), probeDuration(), probeBitRate(), probePrimaryVideoStream(), and probePrimaryAudioStream() provide targeted probe helpers
• getFormats() returns parsed MpegFormat rows from -formats
• getSupportedVideoExtensions(), getSupportedVideoInputExtensions(), and getSupportedVideoOutputExtensions() return common video extensions inferred from the detected formats
• getFfmpegVersionInfo() and getFfprobeVersionInfo() parse version output into MpegVersionInfo
• transcode(), remux(), and extractFrame() wrap common ffmpeg operations
• MpegException includes the command, arguments, exit code, stdout, stderr, and original cause when available