ptr727.MediaTools 1.0.4

MediaTools

C# .NET library for creating CLI arguments for various media processing tools using fluent builders.

Build and Distribution

• Source Code: GitHub - Source code, issues, discussions, and CI/CD pipelines.
• Binary Releases: GitHub Releases - Pre-compiled binaries for Windows, Linux, and macOS.
• NuGet Packages NuGet Packages - .NET libraries published to NuGet.org.

Build Status

Releases

Supported CLI Tools

• 7-Zip: 7z, 7zr, 7za
• ExifTool: exiftool.
• FFmpeg: ffmpeg, ffprobe.
• HandBrake: HandBrakeCLI
• MediaInfo: mediainfo.
• MKVToolNix: mkvmerge, mkvpropedit.
• Whisper: whisper-ctranslate2.

Release Notes

Version: 1.0:

Summary:

• Initial release.

See Release History for complete release notes and older versions.

Getting Started

Get started with MediaTools in three easy steps:

1. Add the library to your C# project:

   # From the developer shell in your project directory
   dotnet add package ptr727.MediaTools
   

2. Install CLI tools on your system:

   ℹ️ Note: Source the tools from your preferred distributions.

   # On Windows install using WinGet
   winget install 7zip.7zr
   winget install Gyan.FFmpeg
   winget install HandBrake.HandBrake.CLI
   winget install MediaArea.MediaInfo
   winget install MoritzBunkus.MKVToolNix --installer-type portable
   winget install OliverBetz.ExifTool
   

   # On Linux install using APT
   apt install exiftool
   apt install ffmpeg
   apt install handbrake-cli
   apt install mediainfo
   apt install mkvtoolnix
   apt install p7zip-full
   

   # Install whisper-ctranslate2 using pipx
   pipx install whisper-ctranslate2
   

3. Write some code:

   dotnet add package ptr727.MediaTools
   

Table of Contents

• Build and Distribution
  • Build Status
  • Releases
  • Supported CLI Tools
  • Release Notes
• Getting Started
• Table of Contents
• Use Cases
• Usage
  • FFmpeg
  • FFprobe
  • MkvMerge
  • MkvPropEdit
  • MediaInfo
  • HandBrake
  • ExifTool
  • 7-Zip
  • Whisper
• Logging
• Samples
• Questions or Issues
• Alternative Libraries
• 3rd Party Tools
• License

Use Cases

ℹ️ TL;DR: This library simplifies creating CLI arguments using builder style patterns.

• Simplified CLI argument construction using fluent builder patterns.
• Simplified execution of CLI tools using CliWrap.

Usage

ℹ️ Note: Not all command sets are complete, refer to alternative libraries that may offer more complete implementations for specific tools.

⚠️ Warning: XML Docs for public API's were generated by AI from CLI docs, verify correctness of command usage.

FFmpeg

FFmpeg - Documentation

FFmpeg - Installation

ℹ️ Note: The ffmpeg package installs both ffmpeg and ffprobe.

FFmpeg - Code Examples

FFprobe

ℹ️ Note: ffprobe is part of the ffmpeg package.

FFprobe - Documentation

FFprobe - Installation

FFprobe - Code Examples

MkvMerge

ℹ️ Note: mkvmerge is part of the MKVToolNix package.

MkvMerge - Documentation

Documentation references:

• MkvMerge user guide.
• mkvmerge --help CLI Help.

MkvMerge - Installation

Install MKVToolNix mkvmerge and mkvpropedit CLI tools:

# On Windows install MKVToolNix using WinGet
winget install MoritzBunkus.MKVToolNix --installer-type portable

# On Linux install MKVToolNix using APT
apt install mkvtoolnix

ℹ️ Note: The MKVToolNix package installs both mkvmerge and mkvpropedit.

MkvMerge - Code Examples

Use MkvMerge.Builder and MkvMerge.Command to build and execute arguments:

// Merge multiple files together
ArgumentsBuilder args = MediaTools
    .MkvMerge.Builder.Create()
    .WithGlobalOptions(global => global.Output("merged.mkv"))
    .WithInputFiles()
    .WithInputOptions(input => input.InputFile("part1.mkv").Append().InputFile("part2.mkv"))
    .Build();

CommandResult result = await MkvMerge.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

// Add chapters and normalize IETF language tags
ArgumentsBuilder args = MediaTools
    .MkvMerge.Builder.Create()
    .WithGlobalOptions(global =>
        global.Output("chapters.mkv")
            .Chapters("chapters.xml")
            .ChapterLanguage("eng")
            .NormalizeLanguageIetfExtended()
    )
    .WithInputFiles()
    .WithInputOptions(input => input.InputFile("video.mkv"))
    .Build();

CommandResult result = await MkvMerge.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

ℹ️ Note: See SandBox/MkvMerge/Builder.cs for more examples.

MkvPropEdit

ℹ️ Note: mkvpropedit is part of the MKVToolNix package.

MkvPropEdit - Documentation

Documentation references:

• MkvPropEdit user guide.
• mkvpropedit --help CLI Help.

MkvPropEdit - Installation

Follow the MkvMerge - Installation instructions.

MkvPropEdit - Code Examples

Use MkvPropEdit.Builder and MkvPropEdit.Command to build and execute arguments:

// Set track properties like name, language, and flags
ArgumentsBuilder args = MediaTools
    .MkvPropEdit.Builder.Create()
    .Edit("track:v1")
    .Set("name", "English")
    .Set("language", "eng")
    .Set("flag-default", "1")
    .InputFile("video.mkv")
    .Build();

CommandResult result = await MkvPropEdit.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

// Replace tags for all tracks
ArgumentsBuilder args = MediaTools
    .MkvPropEdit.Builder.Create()
    .Tags("all", "tags.xml")
    .NormalizeLanguageIETF("canonical")
    .InputFile("video.mkv")
    .Build();

CommandResult result = await MkvPropEdit.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

ℹ️ Note: See SandBox/MkvPropEdit/Builder.cs for more examples.

MediaInfo

MediaInfo - Documentation

MediaInfo - Installation

MediaInfo - Code Examples

HandBrake

HandBrake - Documentation

HandBrake - Installation

HandBrake - Code Examples

ExifTool

ExifTool - Documentation

• ExifTool user guide.
• exiftool Linux man page.
• exiftool -h CLI Help.

ExifTool - Installation

Install ExifTool exiftool CLI tool:

# On Windows install ExifTool using WinGet
winget install OliverBetz.ExifTool

# On Linux install ExifTool using APT
apt install exiftool

ExifTool - Code Examples

// Read metadata with conditions and sidecar output
ArgumentsBuilder args = MediaTools
    .ExifTool.Builder.Create()
    .Read()
    .AddReadOptions(read =>
        read.Verbose(2)
            .Condition("$FileType eq 'JPEG'")
            .Tags("EXIF:DateTimeOriginal", "XMP:Rating")
            .CsvDelimiter("|")
            .Sidecar("txt", overwrite: true)
    )
    .WithInputs()
    .AddInput("photo.jpg")
    .Build();

CommandResult result = await ExifTool.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

// Write metadata with values from file and overwrite in place
ArgumentsBuilder args = MediaTools
    .ExifTool.Builder.Create()
    .Write()
    .AddWriteOptions(write =>
        write.Tag("XMP:Rating", "5")
            .TagValueFromFile("Comment", "notes.txt")
            .OverwriteOriginalInPlace()
            .PreserveFileTimes()
    )
    .WithInputs()
    .AddInput("photo.jpg")
    .Build();

CommandResult result = await ExifTool.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

ℹ️ Note: See SandBox/ExifTool/Builder.cs for more examples.

7-Zip

7-Zip - Documentation

Documentation references:

• User Guide.
• 7z Linux man page.
• 7za Linux man page.
• 7z --help CLI Help.

7-Zip - Installation

Install 7-Zip 7z, 7za, or 7zr CLI tools:

# On Windows install 7z or 7zr using WinGet
winget install 7Zip.7Zip
winget install 7Zip.7zr

ℹ️ Note: By default 7z installs at C:\Program Files\7-Zip\7z.exe but does not register in PATH, while 7zr does register in PATH.

# On Linux install 7z or 7za using APT
apt install p7zip-full

7-Zip - Code Examples

Use SevenZip.Builder and SevenZip.Command to build and execute arguments:

// Create a new archive
ArgumentsBuilder args = Builder
    .Create()
    .Add()
    .AddGlobalOptions(global =>
        global.ArchiveType("7z").CompressionMethod("mx=9").Recurse().ShowTime().AssumeYes()
    )
    .WithInputs()
    .AddInputOptions(input =>
        input
            .ArchiveName("backup.7z")
            .Directory(@"C:\Documents")
            .Files("file1.txt", "file2.pdf")
    )
    .WithOutputs()
    .Build();

CommandResult result = await SevenZip.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

// Extract from an archive
ArgumentsBuilder args = Builder
    .Create()
    .Extract()
    .AddGlobalOptions(global =>
        global
            .OutputDirectory(@"C:\Output")
            .Password("SecurePassword123")
            .OverwriteMode("a")
            .Recurse()
            .ShowTime()
            .AssumeYes()
    )
    .WithInputs()
    .AddInputOptions(input => input.ArchiveName("archive.7z").Wildcard("*.txt"))
    .WithOutputs()
    .Build();

CommandResult result = await SevenZip.Command.ExecuteAsync(args);
Console.WriteLine($"Exit code: {result.ExitCode}");

// Get installed version
string? version = await SevenZip.Command.GetVersionAsync();
Console.WriteLine($"Version: {version}");

ℹ️ Note: See SandBox/SevenZip/Builder.cs for more examples.

Whisper

Whisper - Documentation

Documentation references:

• whisper-ctranslate2 GitHub Project.
• whisper-ctranslate2 -h CLI Help.

Whisper - Installation

Install whisper-ctranslate2 using pipx:

# On Windows install Python using WinGet
winget install Python.Python.3.13
pip install pipx
pipx ensurepath

# On Linux install Python using APT
apt install python3 python3-pip python3-venv pipx
pipx ensurepath

# Install using pipx
pipx install whisper-ctranslate2
whisper-ctranslate2 --version

Whisper - Code Examples

Use Whisper.Builder and Whisper.Command to build and execute arguments:

// Execute transcription command
ArgumentsBuilder args = Builder
    .Create()
    .AddOptions(options =>
        options.Model("medium")
            .Language("en")
            .Task("transcribe")
            .Device("cpu")
            .ComputeType("int8")
            .VadFilter(true)
            .Batched(true)
            .BatchSize(16)
            .InitialPrompt("Two people having a casual conversation in English")
            .OutputFormat("json")
            .PrettyJson(true)
            .OutputDirectory("/transcriptions")
    )
    .WithInputs()
    .AddInputOptions(input => input.AudioFiles("test.wav"))
    .Build();

BufferedCommandResult result = await Whisper.Command.ExecuteBufferedAsync(
    args
);
Console.WriteLine($"Exit code: {result.ExitCode}");

ℹ️ Note: See SandBox/Whisper/Builder.cs for more examples.

Logging

Capture log output by configuring an ILoggerFactory in the Options class:

E.g. Using a Serilog console logger:

// Create a Serilog logger
Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .CreateLogger();

// Set the global logger factory to use the Serilog logger
MediaTools.Options.SetGlobalFactory(new SerilogLoggerFactory(Log.Logger, dispose: false));

Samples

Sample media was created using FFmpeg.

ffmpeg -y -f lavfi -i testsrc=duration=60:size=1920x1080:rate=30 -c:v libx264 -pix_fmt yuv420p testsrc.mp4
ffmpeg -y -f lavfi -i testsrc2=duration=60:size=1920x1080:rate=30 -c:v libx264 -pix_fmt yuv420p testsrc2.mp4

Questions or Issues

For General Questions:

• Use the Discussions forum for general questions, feature requests, and sharing examples.

For Bug Reports:

• Ask in the Discussions forum if you are not sure if it is a bug.
• Check the existing Issues tracker for known problems.
• Check that the issue is not with the media tool itself, and not the CLI wrapper.
• If the issue is unique and a bug, file it in Issues, and include all pertinent steps to reproduce the issue.

Alternative Libraries

ℹ️ Note: This is not an exhaustive list and includes other platforms.

Builder style libraries that may offer more complete coverage for specific tools:

• ffmpeg-python: FFmpeg (Python).
• FFMpegCore: FFmpeg (.NET).
• node-fluent-ffmpeg: FFmpeg (Node).
• pyexiftool: ExifTool (Python).
• pyhandbrake: HandBrake (Python).
• pymkv2: MKVToolNix (Python).
• typed-ffmpeg: FFmpeg (Python).
• Xabe.FFmpeg: FFmpeg (.NET).

3rd Party Tools

3rd Party tools used in this project:

• AwesomeAssertions
• Bring Your Own Badge
• CliWrap
• Create Pull Request
• CSharpier
• GH Release
• Git Auto Commit
• GitHub Actions
• GitHub Dependabot
• Husky.Net
• Nerdbank.GitVersioning
• Serilog
• xUnit.Net

License

Licensed under the MIT License