SharpISOBMFF 0.4.0

dotnet add package SharpISOBMFF --version 0.4.0
                    
NuGet\Install-Package SharpISOBMFF -Version 0.4.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="SharpISOBMFF" Version="0.4.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SharpISOBMFF" Version="0.4.0" />
                    
Directory.Packages.props
<PackageReference Include="SharpISOBMFF" />
                    
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 SharpISOBMFF --version 0.4.0
                    
#r "nuget: SharpISOBMFF, 0.4.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 SharpISOBMFF@0.4.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=SharpISOBMFF&version=0.4.0
                    
Install as a Cake Addin
#tool nuget:?package=SharpISOBMFF&version=0.4.0
                    
Install as a Cake Tool

SharpMP4

Simple lightweight mp4/fmp4/mov/m4v reader/writer. Supports H261/H262/H263/MPEG4/H264/H265/H266/VP9/AV1/AV2/ProRes/Motion JPEG for video and AAC/Opus/MP3 (and MP2)/FLAC/ALAC/AC-3/E-AC-3/DTS (and DTS-HD)/AMR/PCM (and G.711) for audio. No platform dependencies, easily portable cross-platform. It was designed to be a stream-in and stream-out solution for recording streams from IP cameras into MP4 and fragmented MP4.

NuGet version

Supported boxes

The list of all supported boxes, entries and descriptors is here.

Each box says whether it is where its definition places it: box.ValidatePlacement() checks its parent against the containers of its definition in src/SharpISOBMFF/Definitions - a parent box type, the top of the file, a parent class, and of an encrypted or restricted sample entry, the format its frma names. It is for information only: a box elsewhere is read and written all the same. A box whose definition gives no container is not reported.

ToString() of a box, a class, a descriptor or a whole Container describes its fields as they are now - read, or changed since - a line each, as FFmpeg's trace_headers traces a bitstream: the field's position in bits, its name, its bits and its value, the fields and boxes in a box indented a level deeper, and the fields of a loop with their indices. A run of bytes kept in the file (StreamMarker), such as the data of mdat, is shown as ....

            'stts' TimeToSampleBox
0             size                       00000000000000000000000000100000 = 32
32            type                       01110011011101000111010001110011 = 1937011827 ('stts')
64            version                                            00000000 = 0
72            flags                              000000000000000000000000 = 0
96            entry_count                00000000000000000000000000000001 = 1
128           sample_count[0]            00000000000000000000000000000011 = 3
160           sample_delta[0]            00000000000000000000010000000000 = 1024

Read MP4

To parse an existing mp4/mov/m4v file, first you have to get the stream:

using (Stream inputFileStream = new BufferedStream(new FileStream("frag_bunny.mp4", FileMode.Open, FileAccess.Read, FileShare.Read)))
{
    ...
}

Create a new Container and call Read to get the in-memory representation of all the boxes.

var mp4 = new Container();
mp4.Read(new IsoStream(inputFileStream));

To process this in-memory representation and read the audio/video samples, create a new VideoReader. Disposed, it disposes the tracks it made; the Container and the stream it was read from stay yours:

using VideoReader videoReader = new VideoReader();
videoReader.Parse(mp4);

Now it is possible to get all the tracks from the video:

IEnumerable<ITrack> tracks = videoReader.GetTracks();

To read the samples of the first track, call ReadSample until it returns null:

uint trackID = tracks.First().TrackID;
MediaSample sample;
while ((sample = videoReader.ReadSample(trackID)) != null)
{
    // sample.Data, sample.PTS, sample.DTS, sample.Duration, sample.IsRandomAccessPoint
}

Where trackID is the ID of the track you want to read. A video sample holds its NAL units (or OBUs, frames) as the file has them; ParseSample splits it into them, and GetContainerSamples of the track gives the parameter sets of its sample entry:

IEnumerable<ArraySegment<byte>> units = videoReader.ParseSample(trackID, sample.Data);

Build MP4

To write MP4 into a file, you first have to create the file:

using (Stream output = new BufferedStream(new FileStream("bunny_out.mp4", FileMode.Create, FileAccess.Write, FileShare.Read)))
{
    ...
}

Next, create the builder depending upon the output format. Currently, there are two builders - FragmentedMp4Builder and Mp4Builder.

using IMp4Builder outputBuilder = new Mp4Builder(new SingleStreamOutput(output));

For fragmented MP4 output, use FragmentedMp4Builder with the fragment duration in miliseconds:

// use fragment duration 2 seconds
using IMp4Builder outputBuilder = new FragmentedMp4Builder(new SingleStreamOutput(output), 2000);

To write another format of the MP4 family - .m4v, .m4a, .m4b, .3gp, .3g2 or .mov - set FileFormat before adding the tracks. The ftyp then says what the file is, and the builder refuses a track the format cannot hold, such as video in an .m4a or a second audio track in a 3GP file of the Basic profile:

outputBuilder.FileFormat = Mp4FileFormat.M4A;

Add the H264 video track to the builder instance:

var videoTrack = new H264Track();
outputBuilder.AddTrack(videoTrack);

Add the AAC audio track to the builder instance:

var audioTrack = new AACTrack(2, 44100, 16);
outputBuilder.AddTrack(audioTrack);

Pass the track samples to the builder as follows:

byte[] nalu = ...;
outputBuilder.ProcessTrackSample(videoTrack.TrackID, nalu);
...
byte[] aac = ...;
outputBuilder.ProcessTrackSample(audioTrack.TrackID, aac);

ProcessTrackSample takes H.264/H.265/H.266 NAL units without their start codes. To pass the Annex B byte stream as an encoder hands it out - one or more NAL units, each behind a start code - use ProcessAnnexBTrackSample, which strips the start codes:

byte[] annexB = ...; // 00 00 00 01 67 ... 00 00 00 01 68 ... 00 00 01 65 ...
outputBuilder.ProcessAnnexBTrackSample(videoTrack.TrackID, annexB);

The other audio tracks are made of their codec's configuration, as an encoder hands it out or a file has it, and take a frame a sample:

var flac = new FlacTrack(FlacStreamHeader.Parse(header));     // 'fLaC' and the metadata blocks, STREAMINFO first
var alac = new AlacTrack(alacSpecificConfig);                   // the 24 byte magic cookie
var mp3 = new Mp3Track(2, 44100);                              // MPEG-1 or MPEG-2 audio, by the rate
var ac3 = new AC3Track(AC3SyncFrame.Parse(frame));             // a sync frame's syncinfo and bsi
var eac3 = new EAC3Track(dataRate, substreams);                 // 'dec3''s data rate and independent substreams
var dts = new DtsTrack(DtsFrame.Parse(unit));                   // an access unit: a core frame, the extension substreams after it, or those alone

A DTS track is a 'dtsc', 'dtsh', 'dtsl' or 'dtse' as the stream is made, and DtsTrack.ParseFrames splits an encoder's output into its access units, a sample each. An MP3 encoder hands out one frame or several at a time: the track's ParseFrames splits them, a sample each:

foreach (ArraySegment<byte> frame in mp3.ParseFrames(buffer, 0, length))
    outputBuilder.ProcessTrackSample(mp3.TrackID, frame);

PCM is made of its format and written as QuickTime's lpcm, as Apple's devices write it. It takes a block of frames at a time and writes a sample of each, as QuickTime has it. Reading it, QuickTime's lpcm, sowt, twos, raw , in24, in32, fl32 and fl64 and ISO's ipcm and fpcm are read, and ReadSamples reads a run of frames at once rather than a read of each:

var pcm = new PcmTrack(48000, 2, 16);                           // rate, channels, bits; isFloat and isLittleEndian optional
outputBuilder.ProcessTrackSample(pcm.TrackID, block, block.Length / pcm.BytesPerFrame);
var run = videoReader.ReadSamples(trackID, 4800);               // up to 4800 frames, their duration together

When done, call FinalizeMedia to create the video file. Disposing the builder then lets go of where the samples waited - what FinalizeMedia has not written is not written. The tracks you made are yours to dispose:

outputBuilder.FinalizeMedia();

Extensibility

Logging

There is an IMp4Logger property, Logger, on the Container, IsoStream, VideoReader, ImageReader, the builders, their outputs and the tracks, where you can supply your own logger implementation, or use an existing one. Container, VideoReader and SingleStreamOutput take it in their constructor too, and a builder hands its logger to the tracks added to it that have none of their own:

var logger = new ConsoleMp4Logger();
var mp4 = new Container(logger);
mp4.Read(new IsoStream(inputFileStream) { Logger = logger });
using var videoReader = new VideoReader(logger);
outputBuilder.Logger = logger;

You can also enable/disable different trace levels like:

logger.IsWarningEnabled = false;

Conformance bitstreams

The published conformance suites for H.264, H.265, H.266 and AV1 can be downloaded for testing the parsers against:

.\DownloadConformance.ps1                            # the core sets for all four codecs, about 4.8 GB
.\DownloadConformance.ps1 -Codec H265, H266          # only some codecs
.\DownloadConformance.ps1 -IncludeSvc -IncludeArgon  # also H.264 SVC (12.9 GB) and AV1 Argon Streams (7 GB)

They go into the conformance folder, which git ignores. Running the script again skips what is already there. The reference decoder's output - decoded pictures, traces and logs, which make the H.264 suites several times their download size - is left out unless -KeepReference is given. It works in Windows PowerShell 5.1 and PowerShell 7.

Credits

Huge inspiration for this project was the mp4parser https://github.com/sannies/mp4parser, thank you very much!

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 is compatible.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on SharpISOBMFF:

Package Downloads
SharpMP4

Simple lightweight mp4/m4v/mov reader/writer. Supports H261/H262/H263/MPEG4/H264/H265/H266/VP9/AV1/AV2/ProRes for video, AAC/AC3/ALAC/AMR/DTS/EAC3/FLAC/MP3/Opus/PCM for audio and HEIC/HEIF/AVIF for images.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.4.0 157 11/13/2026
0.3.2 1,888 9/10/2026
0.3.1 1,403 6/6/2026
0.3.0 893 4/12/2026
0.2.2 675 2/12/2026
0.2.1 621 12/10/2025
0.2.0 258 11/15/2025
0.1.3 392 10/28/2025
0.1.2 268 10/26/2025
0.1.1 1,023 8/31/2025
0.1.0 334 8/30/2025