Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 157 additions & 10 deletions src/TagLibSharp2/Core/MediaFile.cs
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ namespace TagLibSharp2.Core;
///
/// <para><b>Reading and Modifying Tags</b></para>
/// <para>
/// Use <see cref="Read"/> or <see cref="ReadAsync"/> to open a file. The result contains
/// Use <see cref="Read(string, IFileSystem)"/> or <see cref="ReadAsync(string, IFileSystem, CancellationToken)"/> to open a file. The result contains
/// the strongly-typed file object (e.g., <see cref="TagLibSharp2.Xiph.FlacFile"/>,
/// <see cref="TagLibSharp2.Mpeg.Mp3File"/>) with Tag and audio property access.
/// Modify tag properties directly on the file object.
Expand Down Expand Up @@ -148,11 +148,39 @@ public static MediaFileResult Read (string path, IFileSystem? fileSystem = null)
ArgumentNullException.ThrowIfNull (path);
#endif

var readResult = FileHelper.SafeReadAllBytes (path, fileSystem);
if (!readResult.IsSuccess)
return MediaFileResult.Failure (readResult.Error!);
var fs = fileSystem ?? DefaultFileSystem.Instance;
if (!fs.FileExists (path))
return MediaFileResult.Failure ($"File not found: {path}");

try {
using var stream = fs.OpenRead (path);
return Read (stream, path, path, fs);
} catch (IOException ex) {
return MediaFileResult.Failure ($"Failed to read file: {ex.Message}");
} catch (UnauthorizedAccessException ex) {
return MediaFileResult.Failure ($"Access denied: {ex.Message}");
}
}

return ReadCore (readResult.Data!.Value, path, fileSystem, rememberPath: true);
/// <summary>
/// Reads a media file from a stream.
/// </summary>
/// <param name="stream">The stream to read. The caller keeps ownership of it.</param>
/// <param name="pathHint">Optional file name used when the bytes do not identify a format.</param>
/// <returns>A result containing the parsed file or an error.</returns>
/// <remarks>
/// A seekable stream is read by the ranges the format needs. MP3, FLAC, and WAV
/// do not read the audio payload. A stream that cannot seek is copied once.
/// </remarks>
public static MediaFileResult Read (Stream stream, string? pathHint = null)
{
#if NETSTANDARD2_0 || NETSTANDARD2_1
if (stream is null)
throw new ArgumentNullException (nameof (stream));
#else
ArgumentNullException.ThrowIfNull (stream);
#endif
return Read (stream, pathHint, sourcePath: null, fileSystem: null);
}

/// <summary>
Expand All @@ -174,12 +202,131 @@ public static async Task<MediaFileResult> ReadAsync (
ArgumentNullException.ThrowIfNull (path);
#endif

var readResult = await FileHelper.SafeReadAllBytesAsync (path, fileSystem, cancellationToken)
.ConfigureAwait (false);
if (!readResult.IsSuccess)
return MediaFileResult.Failure (readResult.Error!);
var fs = fileSystem ?? DefaultFileSystem.Instance;
if (!fs.FileExists (path))
return MediaFileResult.Failure ($"File not found: {path}");

try {
using var stream = fs.OpenRead (path);
return await ReadAsync (stream, path, path, fs, cancellationToken).ConfigureAwait (false);
} catch (IOException ex) {
return MediaFileResult.Failure ($"Failed to read file: {ex.Message}");
} catch (UnauthorizedAccessException ex) {
return MediaFileResult.Failure ($"Access denied: {ex.Message}");
} catch (OperationCanceledException) {
return MediaFileResult.Failure ("Operation was cancelled");
}
}

/// <summary>
/// Reads a media file from a stream asynchronously.
/// </summary>
/// <param name="stream">The stream to read. The caller keeps ownership of it.</param>
/// <param name="pathHint">Optional file name used when the bytes do not identify a format.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>A result containing the parsed file or an error.</returns>
/// <remarks>
/// A seekable stream is read by the ranges the format needs. MP3, FLAC, and WAV
/// do not read the audio payload. A stream that cannot seek is copied once.
/// </remarks>
public static Task<MediaFileResult> ReadAsync (
Stream stream,
string? pathHint = null,
CancellationToken cancellationToken = default)
{
#if NETSTANDARD2_0 || NETSTANDARD2_1
if (stream is null)
throw new ArgumentNullException (nameof (stream));
#else
ArgumentNullException.ThrowIfNull (stream);
#endif
return ReadAsync (stream, pathHint, sourcePath: null, fileSystem: null, cancellationToken);
}

static MediaFileResult Read (Stream stream, string? pathHint, string? sourcePath, IFileSystem? fileSystem)
{
if (!stream.CanSeek)
return RememberMatroskaSource (ReadFromData (StreamBytes.ReadToEnd (stream), pathHint), sourcePath, fileSystem);

if (stream.Position != 0)
stream.Position = 0;

var peek = StreamBytes.ReadAtMost (stream, 4096);
stream.Position = 0;
return RememberMatroskaSource (
OpenDetected (DetectFormat (peek, pathHint), stream, sourcePath, fileSystem, pathHint),
sourcePath,
fileSystem);
}

static async Task<MediaFileResult> ReadAsync (
Stream stream,
string? pathHint,
string? sourcePath,
IFileSystem? fileSystem,
CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested ();
if (!stream.CanSeek)
return RememberMatroskaSource (
ReadFromData (await StreamBytes.ReadToEndAsync (stream, cancellationToken).ConfigureAwait (false), pathHint),
sourcePath,
fileSystem);

if (stream.Position != 0)
stream.Position = 0;

var peek = await StreamBytes.ReadAtMostAsync (stream, 4096, cancellationToken).ConfigureAwait (false);
stream.Position = 0;
var format = DetectFormat (peek, pathHint);
var result = format switch {
MediaFormat.Mp3 => FromMp3 (await Mp3File.ReadAsync (stream, cancellationToken).ConfigureAwait (false)),
MediaFormat.Flac => FromFlac (await FlacFile.ReadAsync (stream, cancellationToken).ConfigureAwait (false)),
MediaFormat.Wav => FromWav (WavFile.Read (stream, sourcePath, fileSystem)),
_ => ReadFromData (await StreamBytes.ReadToEndAsync (stream, cancellationToken).ConfigureAwait (false), pathHint)
};
return RememberMatroskaSource (result, sourcePath, fileSystem);
}

static MediaFileResult OpenDetected (MediaFormat format, Stream stream, string? sourcePath, IFileSystem? fileSystem, string? pathHint) =>
format switch {
MediaFormat.Mp3 => FromMp3 (Mp3File.Read (stream)),
MediaFormat.Flac => FromFlac (FlacFile.Read (stream)),
MediaFormat.Wav => FromWav (WavFile.Read (stream, sourcePath, fileSystem)),
_ => ReadFromData (StreamBytes.ReadToEnd (stream), pathHint)
};

// ReadFromData's path is only an extension hint. A path read can save Matroska back to that file.
static MediaFileResult RememberMatroskaSource (MediaFileResult result, string? sourcePath, IFileSystem? fileSystem)
{
if (sourcePath is not null && result.IsSuccess && result.File is MatroskaFile matroska)
matroska.SetSourcePath (sourcePath, fileSystem);
return result;
}

static MediaFileResult FromMp3 (Mp3FileReadResult result)
{
if (!result.IsSuccess || result.File is null)
return MediaFileResult.Failure (result.Error ?? "Failed to parse MP3 file");
return MediaFileResult.Success (result.File, result.File.Tag, MediaFormat.Mp3);
}

return ReadCore (readResult.Data!.Value, path, fileSystem, rememberPath: true);
static MediaFileResult FromFlac (FlacFileReadResult result)
{
if (!result.IsSuccess || result.File is null)
return MediaFileResult.Failure (result.Error ?? "Failed to parse FLAC file");
return MediaFileResult.Success (result.File, result.File.Tag, MediaFormat.Flac);
}

static MediaFileResult FromWav (WavFileReadResult result)
{
if (!result.IsSuccess || result.File is null)
return MediaFileResult.Failure (result.Error ?? "Failed to parse WAV file");

Tag? tag = result.File.Id3v2Tag is not null
? result.File.Id3v2Tag
: result.File.InfoTag;
return MediaFileResult.Success (result.File, tag, MediaFormat.Wav);
}

/// <summary>
Expand Down
101 changes: 101 additions & 0 deletions src/TagLibSharp2/Core/StreamBytes.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
// Copyright (c) 2025-2026 Stephen Shaw and contributors
// Licensed under the MIT License. See LICENSE file in the project root for full license information.

namespace TagLibSharp2.Core;

/// <summary>
/// Reads a bounded number of bytes from a stream. A short read is the end of the stream.
/// </summary>
internal static class StreamBytes
{
public static byte[] ReadAtMost (Stream stream, int count)
{
if (count <= 0)
return [];

var buffer = new byte[count];
var read = Read (stream, buffer, 0, count);
return read == count ? buffer : Trim (buffer, read);
}

public static async Task<byte[]> ReadAtMostAsync (Stream stream, int count, CancellationToken cancellationToken)
{
if (count <= 0)
return [];

var buffer = new byte[count];
var read = await ReadAsync (stream, buffer, 0, count, cancellationToken).ConfigureAwait (false);
return read == count ? buffer : Trim (buffer, read);
}

public static byte[] ReadToEnd (Stream stream)
{
if (stream.CanSeek) {
var remaining = stream.Length - stream.Position;
if (remaining <= 0)
return [];
if (remaining > int.MaxValue)
throw new IOException ("File is too large to read into memory");
return ReadAtMost (stream, (int)remaining);
}

using var copy = new MemoryStream ();
stream.CopyTo (copy);
return copy.ToArray ();
}

public static async Task<byte[]> ReadToEndAsync (Stream stream, CancellationToken cancellationToken)
{
if (stream.CanSeek) {
var remaining = stream.Length - stream.Position;
if (remaining <= 0)
return [];
if (remaining > int.MaxValue)
throw new IOException ("File is too large to read into memory");
return await ReadAtMostAsync (stream, (int)remaining, cancellationToken).ConfigureAwait (false);
}

using var copy = new MemoryStream ();
await stream.CopyToAsync (copy, 81920, cancellationToken).ConfigureAwait (false);
return copy.ToArray ();
}

static int Read (Stream stream, byte[] buffer, int offset, int count)
{
var read = 0;
while (read < count) {
var n = stream.Read (buffer, offset + read, count - read);
if (n == 0)
break;
read += n;
}

return read;
}

static async Task<int> ReadAsync (Stream stream, byte[] buffer, int offset, int count, CancellationToken cancellationToken)
{
var read = 0;
while (read < count) {
#if NETSTANDARD2_0
var n = await stream.ReadAsync (buffer, offset + read, count - read, cancellationToken).ConfigureAwait (false);
#else
var n = await stream.ReadAsync (buffer.AsMemory (offset + read, count - read), cancellationToken).ConfigureAwait (false);
#endif
if (n == 0)
break;
read += n;
}

return read;
}

static byte[] Trim (byte[] buffer, int length)
{
if (length == 0)
return [];
var exact = new byte[length];
Array.Copy (buffer, exact, length);
return exact;
}
}
Loading
Loading