MediaFile Class

Namespace: Meziantou.Framework.MediaTags
Assembly: Meziantou.Framework.MediaTags.dll
Package: Meziantou.Framework.MediaTags 2.1.6
Source: MediaFile.cs
Available in package assets: net10.0net11.0

Provides static methods for reading and writing media file tags.

public static class MediaFile

Remarks

Writing replaces the tags of a file: the written MediaTagInfo becomes the whole tag, and any field left null is removed from the file rather than left at its current value. To change one field, read the tags first, modify the returned object and write it back.

These methods report problems with the file through the returned MediaTagResult instead of throwing. They still throw for invalid arguments.

Methods

Name	Description
DetectFormat(Stream)	Detects the media format from stream content (magic bytes). The stream position is restored after detection.
DetectFormat(string)	Detects the media format from a file path using both magic bytes and file extension.
ReadTags(Stream, MediaFormat?)	Reads tags from the specified stream, starting at its current position.
ReadTags(string)	Reads tags from the specified file.
RemoveTags(Stream, Stream, MediaFormat)	Removes every tag this library can write, writing the result to the output stream.
RemoveTags(string)	Removes every tag this library can write from the specified file.
WriteTags(Stream, Stream, MediaTagInfo, MediaFormat)	Writes the input stream to the output stream, replacing its tags.
WriteTags(Stream, Stream, MediaTagInfo, MediaFormat, MediaTagWriteOptions)	Writes the input stream to the output stream, replacing its tags, using the specified options.
WriteTags(string, MediaTagInfo)	Replaces the tags of the specified file.
WriteTags(string, MediaTagInfo, MediaTagWriteOptions)	Replaces the tags of the specified file, using the specified options.

DetectFormat overloads

DetectFormat(Stream)

MediaFile.cs

Detects the media format from stream content (magic bytes). The stream position is restored after detection.

public static MediaFormat? DetectFormat(Stream stream)

Parameters

stream Stream: The stream to detect the format from.

Returns

MediaFormat? The detected format, or null if not recognized.

Exceptions

ArgumentNullException: stream is null.

DetectFormat(string)

MediaFile.cs

Detects the media format from a file path using both magic bytes and file extension.

public static MediaFormat? DetectFormat(string filePath)

Parameters

filePath string: The path to the media file.

Returns

MediaFormat? The detected format, or null if not recognized.

Exceptions

ArgumentException: filePath is null or empty.

ReadTags overloads

ReadTags(Stream, MediaFormat?)

MediaFile.cs

Reads tags from the specified stream, starting at its current position.

public static MediaTagResult<MediaTagInfo> ReadTags(Stream stream, MediaFormat? format = null)

Parameters

stream Stream: The seekable stream containing the media file.
format MediaFormat?: The format of the media file. If null, the format is auto-detected.

Returns

MediaTagResult<MediaTagInfo> A result containing the parsed tags, or an error.

Exceptions

ArgumentNullException: stream is null.

ReadTags(string)

MediaFile.cs

Reads tags from the specified file.

public static MediaTagResult<MediaTagInfo> ReadTags(string filePath)

Parameters

filePath string: The path to the media file.

Returns

MediaTagResult<MediaTagInfo> A result containing the parsed tags, or an error.

Exceptions

ArgumentException: filePath is null or empty.

RemoveTags overloads

RemoveTags(Stream, Stream, MediaFormat)

MediaFile.cs

Removes every tag this library can write, writing the result to the output stream.

public static MediaTagResult RemoveTags(Stream inputStream, Stream outputStream, MediaFormat format)

Parameters

inputStream Stream: The seekable stream containing the original media file, read from its current position.
outputStream Stream: The stream to write the modified media file to.
format MediaFormat: The format of the media file.

Returns

MediaTagResult A result indicating success or failure.

Exceptions

ArgumentNullException: inputStream or outputStream is null.

RemoveTags(string)

MediaFile.cs

Removes every tag this library can write from the specified file.

public static MediaTagResult RemoveTags(string filePath)

Parameters

filePath string: The path to the media file.

Returns

MediaTagResult A result indicating success or failure. The file is left untouched when the operation fails.

Exceptions

ArgumentException: filePath is null or empty.

WriteTags overloads

WriteTags(Stream, Stream, MediaTagInfo, MediaFormat)

MediaFile.cs

Writes the input stream to the output stream, replacing its tags.

public static MediaTagResult WriteTags(Stream inputStream, Stream outputStream, MediaTagInfo tags, MediaFormat format)

Parameters

inputStream Stream: The seekable stream containing the original media file, read from its current position.
outputStream Stream: The stream to write the modified media file to.
tags MediaTagInfo: The tags to write. They replace the existing tags: fields left null are removed.
format MediaFormat: The format of the media file.

Returns

MediaTagResult A result indicating success or failure. On failure the content already written to outputStream must be discarded: it is not a valid media file.

Exceptions

ArgumentNullException: inputStream, outputStream or tags is null.

WriteTags(Stream, Stream, MediaTagInfo, MediaFormat, MediaTagWriteOptions)

MediaFile.cs

Writes the input stream to the output stream, replacing its tags, using the specified options.

public static MediaTagResult WriteTags(Stream inputStream, Stream outputStream, MediaTagInfo tags, MediaFormat format, MediaTagWriteOptions options)

Parameters

inputStream Stream: The seekable stream containing the original media file, read from its current position.
outputStream Stream: The stream to write the modified media file to.
tags MediaTagInfo: The tags to write. They replace the existing tags: fields left null are removed.
format MediaFormat: The format of the media file.
options MediaTagWriteOptions: Controls how the tags are written.

Returns

MediaTagResult A result indicating success or failure. On failure the content already written to outputStream must be discarded: it is not a valid media file.

Exceptions

ArgumentNullException: One of the arguments is null.

WriteTags(string, MediaTagInfo)

MediaFile.cs

Replaces the tags of the specified file.

public static MediaTagResult WriteTags(string filePath, MediaTagInfo tags)

Parameters

filePath string: The path to the media file.
tags MediaTagInfo: The tags to write. They replace the existing tags: fields left null are removed from the file.

Returns

MediaTagResult A result indicating success or failure. The file is left untouched when the operation fails.

Exceptions

ArgumentException: filePath is null or empty.
ArgumentNullException: tags is null.

WriteTags(string, MediaTagInfo, MediaTagWriteOptions)

MediaFile.cs

Replaces the tags of the specified file, using the specified options.

public static MediaTagResult WriteTags(string filePath, MediaTagInfo tags, MediaTagWriteOptions options)

Parameters

filePath string: The path to the media file.
tags MediaTagInfo: The tags to write. They replace the existing tags: fields left null are removed from the file.
options MediaTagWriteOptions: Controls how the tags are written.

Returns

MediaTagResult A result indicating success or failure. The file is left untouched when the operation fails.

Exceptions

ArgumentException: filePath is null or empty.
ArgumentNullException: tags or options is null.