Sa.Media.FFmpeg 0.20.0

dotnet add package Sa.Media.FFmpeg --version 0.20.0
                    
NuGet\Install-Package Sa.Media.FFmpeg -Version 0.20.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sa.Media.FFmpeg" Version="0.20.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Sa.Media.FFmpeg" Version="0.20.0" />
                    
Directory.Packages.props
<PackageReference Include="Sa.Media.FFmpeg" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Sa.Media.FFmpeg --version 0.20.0
                    
#r "nuget: Sa.Media.FFmpeg, 0.20.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Sa.Media.FFmpeg@0.20.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Sa.Media.FFmpeg&version=0.20.0
                    
Install as a Cake Addin
#tool nuget:?package=Sa.Media.FFmpeg&version=0.20.0
                    
Install as a Cake Tool

Sa.Media.FFmpeg

English | Русский

Cross-platform .NET wrapper for FFmpeg (Windows x64, Linux x64) with bundled fully static binaries — works out of the box, no system-wide FFmpeg and no codec libraries required. Simplifies audio processing: metadata extraction, format conversion, channel split/join, and DI integration.

Installation

dotnet add package Sa.Media.FFmpeg

Contents

Features

  • 🎵 Metadata extraction — duration, bitrate, format, size via ffprobe
  • 🔊 Audio conversion — PCM S16 LE WAV, PCM S32 LE WAV, raw PCM S16 LE/F32 LE binary, MP3, OGG Vorbis/Opus
  • 🎛️ Channel manipulation — split stereo to mono files, join two monos into stereo (via DI)
  • 📦 Bundled FFmpeg binaries — fully static builds for win-x64 and linux-x64, extracted into the app's output directory at build time (no system install, no shared-library dependencies)
  • 💉 DI support — standard IServiceCollection integration with options configuration
  • ⚡ Streaming I/O — pipe audio directly from streams without intermediate files

Quick Start

Default instances (no setup required)

using Sa.Media.FFmpeg;

// Metadata extraction
var meta = await IFFProbeExecutor.Default.GetMetaInfo("input.mp3");
Console.WriteLine($"Duration: {meta.Duration}s, Format: {meta.FormatName}");

// Get channels and sample rate separately
var (channels, sampleRate) = await IFFProbeExecutor.Default.GetChannelsAndSampleRate("input.mp3");

// Audio conversion
await IFFMpegExecutor.Default.ConvertToPcmS16Le(
    "input.mp3",
    "output.wav",
    outputSampleRate: 16000,
    outputChannelCount: 1);

// PCM S32 LE WAV conversion
await IFFMpegExecutor.Default.ConvertToPcmS32Le(
    "input.mp3",
    "output_s32le.wav",
    outputSampleRate: 48000,
    outputChannelCount: 2);

// PCM F32 LE WAV conversion (float samples with WAV header)
await IFFMpegExecutor.Default.ConvertToPcmF32Le(
    "input.mp3",
    "output_f32le.wav",
    outputSampleRate: 48000,
    outputChannelCount: 2);

// Raw float32 LE binary
await IFFMpegExecutor.Default.ConvertToPcmF32LeRaw(
    "input.mp3",
    "output_raw.f32le",
    outputSampleRate: 48000,
    outputChannelCount: 2);

// Raw PCM S16 LE binary (no WAV header)
await IFFMpegExecutor.Default.ConvertToPcmS16LeRaw(
    "input.mp3",
    "output_raw.s16le",
    outputSampleRate: 16000,
    outputChannelCount: 1);

// Convert preserving original sample rate and channels
await IFFMpegExecutor.Default.ConvertToPcmS16LePreservingFormat(
    "input.mp3",
    "output_preserved.wav");

// MP3 conversion
await IFFMpegExecutor.Default.ConvertToMp3("input.wav", "output.mp3");

// OGG Vorbis conversion
await IFFMpegExecutor.Default.ConvertToOgg("input.wav", "output.ogg", isLibopus: false);

// OGG Opus conversion
await IFFMpegExecutor.Default.ConvertToOgg("input.wav", "output.opus", isLibopus: true);

// Get supported formats/codecs
var formats = await IFFMpegExecutor.Default.GetFormats();
var codecs  = await IFFMpegExecutor.Default.GetCodecs();

// FFmpeg version
var version = await IFFMpegExecutor.Default.GetVersion();

Channel split (stereo → mono files)

Resolve via DI (the class is internal):

// After calling builder.Services.AddSaFFMpeg(...):
var services = builder.Services.BuildServiceProvider();
var splitter = services.GetRequiredService<IPcmS16LeChannelManipulator>();

var resultFiles = await splitter.SplitAsync(
    inputFileName: "stereo.mp3",
    outputFileName: "output",
    outputSampleRate: 16000,
    isOverwrite: true);

// Produces:
//   output_channel_0.wav  — left channel
//   output_channel_1.wav  — right channel

Channel join (mono → stereo)

var merger = services.GetRequiredService<IPcmS16LeChannelManipulator>();

var joined = await merger.JoinAsync(
    leftFileName: "left.wav",
    rightFileName: "right.wav",
    outputFileName: "stereo_output.wav",
    outputSampleRate: 16000);

Streaming conversion (no intermediate files)

await using var inputStream = File.OpenRead("input.mp3");

await IFFMpegExecutor.Default.ConvertToPcmS16Le(
    inputStream,
    inputFormat: "mp3",
    onOutput: async (stream, ct) =>
    {
        // Process WAV stream directly — e.g., feed into AsyncWavReader
        await using var reader = new AsyncWavReader(stream);
        await foreach (var packet in reader.ReadDoubleSamplesAsync(ct))
        {
            Console.WriteLine($"Sample: {packet.Sample:F4}");
        }
    },
    outputSampleRate: 16000,
    outputChannelCount: 1);

Raw streaming conversion

await using var inputStream = File.OpenRead("input.mp3");

await IFFMpegExecutor.Default.ConvertToPcmF32LeRaw(
    inputStream,
    inputFormat: "mp3",
    onOutput: async (rawStream, ct) =>
    {
        // Read raw f32le binary — each float is 4 bytes
        var buffer = new byte[4096];
        while (true)
        {
            var read = await rawStream.ReadAsync(buffer, ct);
            if (read == 0) break;
            // Process raw float32 samples...
        }
    },
    outputSampleRate: 48000,
    outputChannelCount: 2);

Stream-based metadata extraction

await using var stream = File.OpenRead("input.mp3");

var meta = await IFFProbeExecutor.Default.GetMetaInfo(stream, inputFormat: "mp3");
Console.WriteLine($"Duration: {meta.Duration}s, Bitrate: {meta.BitRate} bps");

With DI

AddSaFFMpeg registers FFmpeg through the standard Microsoft.Extensions.Options pipeline and returns the IServiceCollection, so it composes with the other Add... calls. The configure callback receives the IFFMpegBuilder: the section comes from FromConfiguration("…"), the options pipeline from Options(...) — which gets the OptionsBuilder<FFMpegOptions>:

builder.Services.AddSaFFMpeg(o => o.Options(ob => ob.Configure(options =>
{
    options.ExecutablePath = @"C:\tools\ffmpeg.exe"; // optional override
    options.WritableDirectory = @"C:\temp\output";
    options.TimeoutSeconds = 300; // 5 minutes
})));

// Usage:
var sp = builder.Services.BuildServiceProvider();
var executor = sp.GetRequiredService<IFFMpegExecutor>();
var probe    = sp.GetRequiredService<IFFProbeExecutor>();
var manip    = sp.GetRequiredService<IPcmS16LeChannelManipulator>();

Pre- and post-initialisation

The pipeline order is fixed — Configure → PostConfigure → validation — so a value normalised in post-initialisation is what validation sees. Configure runs first and receives the raw values; PostConfigure runs after every Configure and after the registration's own normalisation, so anything you add there sees an already-normalised value:

builder.Services.AddSaFFMpeg(o => o
    .Options(ob => ob.Configure(options => options.ExecutablePath = @"C:\tools\ffmpeg.exe")
    .PostConfigure(options => options.WritableDirectory ??= Path.GetTempPath())
    .Validate(options => options.TimeoutSeconds is null or >= 5, "TimeoutSeconds must be at least 5.")));

The registration's own PostConfigure resolves ExecutablePath and WritableDirectory to full paths and turns a blank value into "unset". The Options(...) actions replay after the section binding and the registration's own checks, so their Configure runs last and their Validate adds to — rather than replaces — the built-in checks.

Configuration section binding

Pass the section via FromConfiguration and the options are bound from IConfiguration:

builder.Services.AddSaFFMpeg(b => b.FromConfiguration("Ffmpeg"));

// appsettings.json:
// {
//   "Ffmpeg": {
//     "ExecutablePath": "/usr/bin/ffmpeg",
//     "WritableDirectory": "/tmp/output",
//     "TimeoutSeconds": 300
//   }
// }

The section binds in a fixed slot before the Options(...) actions replay, so their Configure has the last word when both are used.

One registration per collection

AddSaFFMpeg owns the unnamed FFMpegOptions instance, so a second call throws InvalidOperationException — two registrations would stack both Configure callbacks over the same options and silently merge the settings.


Supported Conversions

Source Target Method Notes
Any FFmpeg-supported PCM S16 LE WAV ConvertToPcmS16Le() Custom sample rate (default 16 kHz), channel count
Any PCM S16 LE WAV ConvertToPcmS16LePreservingFormat() Preserves original sample rate & channels
Any Raw PCM S16 LE binary ConvertToPcmS16LeRaw() No WAV header, custom sample rate/channels
Any PCM S32 LE WAV ConvertToPcmS32Le() 32-bit signed integer, custom sample rate/channels
Any PCM F32 LE WAV ConvertToPcmF32Le() 32-bit IEEE float, custom sample rate/channels
Any Raw PCM F32 LE binary ConvertToPcmF32LeRaw() 32-bit IEEE float, no WAV header
Any MP3 ConvertToMp3() 16 kHz, 128 kbps, libmp3lame
Any OGG Vorbis ConvertToOgg(isLibopus: false) Standard Vorbis codec
Any OGG Opus ConvertToOgg(isLibopus: true) Opus codec

Settings

FFMpegOptions

Property Type Description Default
ExecutablePath string? Full path to ffmpeg/ffprobe binary Auto-discovery (bundled → PATH)
WritableDirectory string? Default directory for bare output file names (names without a directory part); created if missing Unset — bare names stay relative to the process working directory
TimeoutSeconds int? Operation timeout in seconds 300 (5 minutes)

Options are validated at host start (ValidateOnStart): TimeoutSeconds must be non-negative or unset, and WritableDirectory must not point at an existing file — a missing directory is fine, the factory creates it.


Public API Reference

IFFMpegExecutor

Property/Method Returns Description
Default IFFMpegExecutor Static default instance (uses bundled binary)
Executor IFFRawExecutor Underlying raw process executor
GetVersion() Task<string> FFmpeg version string
GetFormats() Task<string> All supported formats
GetCodecs() Task<string> All supported codecs
ConvertToPcmS16Le(file, file, ...) Task<string> Convert to WAV file (PCM S16 LE)
ConvertToPcmS16Le(stream, func, ...) Task Stream-based conversion
ConvertToPcmS16LePreservingFormat(file, file, ...) Task<string> Convert preserving original format
ConvertToPcmS16LeRaw(file, file, ...) Task<string> Convert to raw s16le binary file
ConvertToPcmS16LeRaw(stream, func, ...) Task Stream-based raw s16le conversion
ConvertToPcmS32Le(file, file, ...) Task<string> Convert to WAV file (PCM S32 LE)
ConvertToPcmF32Le(file, file, ...) Task<string> Convert to WAV file (PCM F32 LE)
ConvertToPcmF32LeRaw(file, file, ...) Task<string> Convert to raw f32le binary file
ConvertToPcmF32LeRaw(stream, func, ...) Task Stream-based raw f32le conversion
ConvertToMp3(file, file, ...) Task<string> Convert to MP3
ConvertToOgg(file, file, ...) Task<string> Convert to OGG (Vorbis or Opus)

IFFProbeExecutor

Property/Method Returns Description
Default IFFProbeExecutor Static default instance
Executor IFFRawExecutor Underlying raw process executor
GetChannelsAndSampleRate() Task<(int? channels, int? sampleRate)> Raw channel/sample-rate pair
GetMetaInfo(file) Task<MediaMetadata> Full metadata from file path
GetMetaInfo(stream, format) Task<MediaMetadata> Full metadata from stream

IPcmS16LeChannelManipulator

Method Returns Description
SplitAsync(input, output, ...) Task<IReadOnlyList<string>> Split stereo → separate mono WAVs (naming: {base}_channel_{N}.{ext})
JoinAsync(left, right, output, ...) Task<string> Join two monos → stereo WAV

IFFRawExecutor

Property/Method Returns Description
ExecutablePath string Path to the ffmpeg binary
DefaultTimeout TimeSpan Default operation timeout
ExecuteAsync(args, ...) Task<ProcessExecutionResult> Execute FFmpeg with arguments
ExecuteStdOutAsync(args, stream, func, ...) Task Stream stdin/stdout through FFmpeg

Domain Types

MediaMetadata

public sealed record MediaMetadata(
    double? Duration = null,
    string? FormatName = null,
    int? BitRate = null,
    long? Size = null)
{
    public static readonly MediaMetadata Empty = new();
}

Size is long? (bytes): int overflowed on files over 2 GB, and ffprobe reported garbage for them.

ProcessExecutionResult

public record ProcessExecutionResult(
    int ExitCode,
    string StandardOutput,
    string StandardError);

Exceptions

Exception Namespace When thrown
ProcessExecutionException Sa.Media.FFmpeg.Services FFmpeg exits with non-zero code
ProcessExecutionResultException Sa.Media.FFmpeg.Services Wraps ProcessExecutionResult with formatted message
ProcessStartException Sa.Media.FFmpeg.Services Failed to start FFmpeg process
ProcessTimeoutException Sa.Media.FFmpeg.Services Operation exceeded timeout

Bundled Binaries

FFmpeg builds are packed into the NuGet package and extracted by an MSBuild target into sa/native/ next to the application at build time. No system FFmpeg installation is required.

Supported RIDs: win-x64, linux-x64. Payloads shipped in the package: win-x64 and linux-x64 — the two lists are identical on purpose. Any other RID (win-arm64, Linux arm64, macOS) resolves to no payload: the build emits a loud warning, and at runtime the library falls back to a system FFmpeg (PATH or ExecutablePath).

Static payload

Both payloads are fully static: readelf -d sa/native/ffmpeg has no dynamic section and ldd reports not a dynamic executable. The libav* libraries, the audio codecs (libmp3lame, libopus, libvorbis/libvorbisenc) and libc are all linked in, so nothing has to be installed on the host — libmp3lame0/libopus0/libvorbis* are not needed. Because the ELF needs no interpreter, the same Linux binary also runs on musl distributions (linux-musl-x64 resolves to the linux-x64 payload).

build/build-linux.sh enforces this (--pkg-config-flags=--static plus -static) and fails the build if a codec library leaks back into the dynamic dependencies:

readelf -d sa/native/ffmpeg | grep NEEDED   # no output expected

⚠️ No fallback from a broken bundle. Discovery takes the first existing file, so when sa/native/ffmpeg is present but cannot run, the system FFmpeg is not tried — fix the bundle or set FFMpegOptions.ExecutablePath. The real cause is surfaced: GetVersion(), GetFormats() and GetCodecs() throw ProcessExecutionResultException with the exit code and the ffmpeg stderr tail.

Discovery order:

  1. AppContext.BaseDirectory/ffmpeg
  2. AppContext.BaseDirectory/sa/native/ffmpeg
  3. System PATH, plus common install dirs (Program Files\ffmpeg\bin on Windows; /usr/local/bin, /usr/bin, /bin on Unix)

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.20.0 63 11/13/2026
0.18.0 104 11/3/2026
0.17.0 97 10/29/2026
0.16.1 103 10/19/2026
0.16.0 99 10/14/2026
0.15.0 102 10/2/2026
0.13.0 133 8/2/2026
0.12.0 136 7/28/2026
0.11.0 126 7/14/2026
0.10.0 130 7/2/2026
0.9.1 124 4/29/2026
0.9.0 128 3/20/2026
0.8.1 130 3/12/2026
0.8.0 131 2/10/2026
0.7.0 143 1/27/2026
0.6.0 146 1/15/2026
0.5.0 137 12/29/2025
0.4.0 325 12/17/2025
0.3.1 188 10/31/2025
0.3.0 183 10/17/2025
Loading failed