Reading, Writing and Converting

Reading Files

Each format exposes a singleton IOFileFormat instance via its Instance property. Call Read with a Stream or a byte[]:

using var stream = File.OpenRead("tape.tap");
TapFile tap = TapFormat.Instance.Read(stream);

// Or from a byte array:
byte[] bytes = File.ReadAllBytes("tape.tap");
TapFile tap = TapFormat.Instance.Read(bytes);

The returned object is a strongly-typed subclass of IOFile specific to the format.

Writing Files

Pass the file object and a Stream to Write:

using var stream = File.Create("output.tap");
TapFormat.Instance.Write(tap, stream);

There are also overloads that write directly to a file path, or return a byte[]:

// Write to a file path:
TapFormat.Instance.Write(tap, "/path/to/output.tap");

// Write to a byte array:
byte[] bytes = TapFormat.Instance.Write(tap);

Converting Between Formats

IOFileConversion provides static methods to convert a file from one format to another. Conversions are registered by each format and can be discovered at runtime.

Converting to a Known Type

Use the generic Convert<TTarget> overload when you know the target type at compile time:

TapFile tap = TapFormat.Instance.Read(stream);

// Convert TAP → TZX:
TzxFile tzx = IOFileConversion.Convert<TzxFile>(tap);

// Convert TAP → PZX:
PzxFile pzx = IOFileConversion.Convert<PzxFile>(tap);

// Convert TZX → TAP:
TapFile tapFromTzx = IOFileConversion.Convert<TapFile>(tzx);

Converting with Error Handling

Use TryConvert when the conversion might fail. This is useful for conversions like TZX → TAP or PZX → TAP where not all block types can be represented:

if (IOFileConversion.TryConvert(tzx, TapFormat.Instance, out var result, out var error))
{
    TapFormat.Instance.Write(result, "output.tap");
}
else
{
    Console.WriteLine($"Conversion failed: {error}");
}

Converting to WAV

Use ConvertToWav to produce a WAV audio file from any tape format. An optional sample rate can be specified (default is 44100 Hz):

WavFile wav = IOFileConversion.ConvertToWav(tap);

// With a custom sample rate:
WavFile wav = IOFileConversion.ConvertToWav(tap, sampleRateHz: 48000);

Discovering Supported Conversions

Use GetSupportedConversionFormats to discover which target formats are available for a given source:

IReadOnlyList<IOFileFormat> targets = IOFileConversion.GetSupportedConversionFormats(TapFormat.Instance);
foreach (var format in targets)
{
    Console.WriteLine(format.Name);
}