Meziantou.Framework

JpegXlTranscoder Class

Namespace
Meziantou.Framework.Imaging
Assembly
Meziantou.Framework.Imaging.dll
Package
Meziantou.Framework.Imaging 1.2.11
Source
JpegXlTranscoder.cs
Available in package assets
net10.0net11.0

Converts between JPEG files and JPEG XL files without decoding pixels: a JPEG XL file can hold the quantized coefficients of a JPEG file, about a fifth smaller, with the data that rebuild the JPEG file byte for byte.

public static class JpegXlTranscoder

Remarks

These operations work on files, not on images: an Image holds pixels, and a JPEG file cannot be rebuilt from pixels. Image.Load reads the pixels of such a JPEG XL file like the ones of any other.

Nothing is approximated: an input that cannot be converted exactly throws, and the destination is only written once the whole output is known. A path destination is replaced once it is written.

Methods

NameDescription
HasJpegReconstructionData(Stream, JpegXlTranscodeOptions?)Tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.
HasJpegReconstructionData(ReadOnlySpan<byte>, JpegXlTranscodeOptions?)Tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.
HasJpegReconstructionData(string, JpegXlTranscodeOptions?)Tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.
HasJpegReconstructionDataAsync(Stream, JpegXlTranscodeOptions?, CancellationToken)Asynchronously tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.
RecompressJpeg(Stream, Stream, JpegXlTranscodeOptions?)Recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it: JpegXlTranscoder.ReconstructJpeg gives the JPEG file back, byte for byte. No pixel is decoded, and nothing is lost.
RecompressJpeg(ReadOnlySpan<byte>, Stream, JpegXlTranscodeOptions?)Recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it: JpegXlTranscoder.ReconstructJpeg gives the JPEG file back, byte for byte. No pixel is decoded, and nothing is lost.
RecompressJpeg(string, string, JpegXlTranscodeOptions?)Recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it.
RecompressJpegAsync(Stream, Stream, JpegXlTranscodeOptions?, CancellationToken)Asynchronously recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it.
RecompressJpegAsync(string, string, JpegXlTranscodeOptions?, CancellationToken)Asynchronously recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it.
ReconstructJpeg(Stream, Stream, JpegXlTranscodeOptions?)Rebuilds the JPEG file a JPEG XL file was made from, byte for byte.
ReconstructJpeg(ReadOnlySpan<byte>, Stream, JpegXlTranscodeOptions?)Rebuilds the JPEG file a JPEG XL file was made from, byte for byte.
ReconstructJpeg(string, string, JpegXlTranscodeOptions?)Rebuilds the JPEG file a JPEG XL file was made from, byte for byte.
ReconstructJpegAsync(Stream, Stream, JpegXlTranscodeOptions?, CancellationToken)Asynchronously rebuilds the JPEG file a JPEG XL file was made from, byte for byte.
ReconstructJpegAsync(string, string, JpegXlTranscodeOptions?, CancellationToken)Asynchronously rebuilds the JPEG file a JPEG XL file was made from, byte for byte.
TryReconstructJpeg(Stream, Stream, JpegXlTranscodeOptions?)Rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.
TryReconstructJpeg(ReadOnlySpan<byte>, Stream, JpegXlTranscodeOptions?)Rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.
TryReconstructJpeg(string, string, JpegXlTranscodeOptions?)Rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.
TryReconstructJpegAsync(Stream, Stream, JpegXlTranscodeOptions?, CancellationToken)Asynchronously rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.

HasJpegReconstructionData overloads

HasJpegReconstructionData(Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.

public static bool HasJpegReconstructionData(Stream jpegXl, JpegXlTranscodeOptions? options = null)
Parameters
jpegXl Stream
The JPEG XL file.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Returns

bool true when the data are present; they are not validated.

Exceptions
ArgumentNullException
jpegXl is null.
ArgumentException
jpegXl is not readable.
Remarks

Encoders write the data before the image: the answer is then known from the start of the file, and nothing else is read. When no data precede an image that could be the one of a JPEG file, the rest of the file is read, without decoding it, since the data may follow the image.

HasJpegReconstructionData(ReadOnlySpan<byte>, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.

public static bool HasJpegReconstructionData(ReadOnlySpan<byte> jpegXl, JpegXlTranscodeOptions? options = null)
Parameters
jpegXl ReadOnlySpan<byte>
The JPEG XL file.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Returns

bool true when the data are present; they are not validated.

Exceptions
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file.
InvalidImageContentException
The part of the file that is read is malformed or truncated.
Remarks

Encoders write the data before the image: the answer is then known from the start of the file, and nothing else is read. When no data precede an image that could be the one of a JPEG file, the rest of the file is read, without decoding it, since the data may follow the image.

HasJpegReconstructionData(string, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.

public static bool HasJpegReconstructionData(string jpegXlPath, JpegXlTranscodeOptions? options = null)
Parameters
jpegXlPath string
The path of the JPEG XL file.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Returns

bool true when the data are present; they are not validated.

Exceptions
ArgumentNullException
jpegXlPath is null.
ArgumentException
jpegXlPath is empty.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file.
InvalidImageContentException
The part of the file that is read is malformed or truncated.

HasJpegReconstructionDataAsync(Stream, JpegXlTranscodeOptions?, CancellationToken)

JpegXlTranscoder.cs

Asynchronously tells whether a JPEG XL file holds the data that rebuild the JPEG file it was made from.

public static Task<bool> HasJpegReconstructionDataAsync(Stream jpegXl, JpegXlTranscodeOptions? options = null, CancellationToken cancellationToken = default)

Parameters

jpegXl Stream
The JPEG XL file.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
cancellationToken CancellationToken
The token to monitor for cancellation requests.

Returns

Task<bool> true when the data are present; they are not validated.

Exceptions

ArgumentNullException
jpegXl is null.
ArgumentException
jpegXl is not readable.

RecompressJpeg overloads

RecompressJpeg(Stream, Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it: JpegXlTranscoder.ReconstructJpeg gives the JPEG file back, byte for byte. No pixel is decoded, and nothing is lost.

public static void RecompressJpeg(Stream jpeg, Stream destination, JpegXlTranscodeOptions? options = null)
Parameters
jpeg Stream
The JPEG file.
destination Stream
Receives the JPEG XL file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Exceptions
ArgumentNullException
jpeg or destination is null.
ArgumentException
jpeg is not readable, or destination is not writable.

RecompressJpeg(ReadOnlySpan<byte>, Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it: JpegXlTranscoder.ReconstructJpeg gives the JPEG file back, byte for byte. No pixel is decoded, and nothing is lost.

public static void RecompressJpeg(ReadOnlySpan<byte> jpeg, Stream destination, JpegXlTranscodeOptions? options = null)
Parameters
jpeg ReadOnlySpan<byte>
The JPEG file.
destination Stream
Receives the JPEG XL file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Exceptions
ArgumentNullException
destination is null.
ArgumentException
destination is not writable.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG file, or it is a JPEG file that a JPEG XL frame cannot hold: four components, sampling factors other than 1 or 2, arithmetic coding, 12-bit samples, or entropy-coded data that could not be rebuilt byte for byte.
InvalidImageContentException
The file is malformed or truncated.
ImageResourceLimitException
A configured limit is exceeded.

RecompressJpeg(string, string, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it.

public static void RecompressJpeg(string jpegPath, string destinationPath, JpegXlTranscodeOptions? options = null)
Parameters
jpegPath string
The path of the JPEG file.
destinationPath string
The path of the JPEG XL file, which is created or replaced once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Exceptions
ArgumentNullException
jpegPath or destinationPath is null.
ArgumentException
jpegPath or destinationPath is empty.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG file, or it is a JPEG file that a JPEG XL frame cannot hold.
InvalidImageContentException
The file is malformed or truncated.
ImageResourceLimitException
A configured limit is exceeded.

RecompressJpegAsync overloads

RecompressJpegAsync(Stream, Stream, JpegXlTranscodeOptions?, CancellationToken)

JpegXlTranscoder.cs

Asynchronously recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it.

public static Task RecompressJpegAsync(Stream jpeg, Stream destination, JpegXlTranscodeOptions? options = null, CancellationToken cancellationToken = default)
Parameters
jpeg Stream
The JPEG file.
destination Stream
Receives the JPEG XL file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
cancellationToken CancellationToken
The token to monitor for cancellation requests.
Returns

Task A task that completes when the file is written.

Exceptions
ArgumentNullException
jpeg or destination is null.
ArgumentException
jpeg is not readable, or destination is not writable.

RecompressJpegAsync(string, string, JpegXlTranscodeOptions?, CancellationToken)

JpegXlTranscoder.cs

Asynchronously recompresses a JPEG file as a JPEG XL file that holds its quantized coefficients and the data that rebuild it.

public static Task RecompressJpegAsync(string jpegPath, string destinationPath, JpegXlTranscodeOptions? options = null, CancellationToken cancellationToken = default)
Parameters
jpegPath string
The path of the JPEG file.
destinationPath string
The path of the JPEG XL file, which is created or replaced once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
cancellationToken CancellationToken
The token to monitor for cancellation requests.
Returns

Task A task that completes when the file is written.

Exceptions
ArgumentNullException
jpegPath or destinationPath is null.
ArgumentException
jpegPath or destinationPath is empty.

ReconstructJpeg overloads

ReconstructJpeg(Stream, Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Rebuilds the JPEG file a JPEG XL file was made from, byte for byte.

public static void ReconstructJpeg(Stream jpegXl, Stream destination, JpegXlTranscodeOptions? options = null)
Parameters
jpegXl Stream
The JPEG XL file.
destination Stream
Receives the JPEG file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Exceptions
ArgumentNullException
jpegXl or destination is null.
ArgumentException
jpegXl is not readable, or destination is not writable.

ReconstructJpeg(ReadOnlySpan<byte>, Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Rebuilds the JPEG file a JPEG XL file was made from, byte for byte.

public static void ReconstructJpeg(ReadOnlySpan<byte> jpegXl, Stream destination, JpegXlTranscodeOptions? options = null)
Parameters
jpegXl ReadOnlySpan<byte>
The JPEG XL file.
destination Stream
Receives the JPEG file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Exceptions
ArgumentNullException
destination is null.
ArgumentException
destination is not writable.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file, or it does not hold the data that rebuild a JPEG file (JpegXlTranscoder.TryReconstructJpeg returns false instead).
InvalidImageContentException
The file is malformed or truncated, or its reconstruction data do not match its image.
ImageResourceLimitException
A configured limit is exceeded.

ReconstructJpeg(string, string, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Rebuilds the JPEG file a JPEG XL file was made from, byte for byte.

public static void ReconstructJpeg(string jpegXlPath, string destinationPath, JpegXlTranscodeOptions? options = null)
Parameters
jpegXlPath string
The path of the JPEG XL file.
destinationPath string
The path of the JPEG file, which is created or replaced once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Exceptions
ArgumentNullException
jpegXlPath or destinationPath is null.
ArgumentException
jpegXlPath or destinationPath is empty.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file, or it does not hold the data that rebuild a JPEG file.
InvalidImageContentException
The file is malformed or truncated, or its reconstruction data do not match its image.
ImageResourceLimitException
A configured limit is exceeded.

ReconstructJpegAsync overloads

ReconstructJpegAsync(Stream, Stream, JpegXlTranscodeOptions?, CancellationToken)

JpegXlTranscoder.cs

Asynchronously rebuilds the JPEG file a JPEG XL file was made from, byte for byte.

public static Task ReconstructJpegAsync(Stream jpegXl, Stream destination, JpegXlTranscodeOptions? options = null, CancellationToken cancellationToken = default)
Parameters
jpegXl Stream
The JPEG XL file.
destination Stream
Receives the JPEG file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
cancellationToken CancellationToken
The token to monitor for cancellation requests.
Returns

Task A task that completes when the file is written.

Exceptions
ArgumentNullException
jpegXl or destination is null.
ArgumentException
jpegXl is not readable, or destination is not writable.

ReconstructJpegAsync(string, string, JpegXlTranscodeOptions?, CancellationToken)

JpegXlTranscoder.cs

Asynchronously rebuilds the JPEG file a JPEG XL file was made from, byte for byte.

public static Task ReconstructJpegAsync(string jpegXlPath, string destinationPath, JpegXlTranscodeOptions? options = null, CancellationToken cancellationToken = default)
Parameters
jpegXlPath string
The path of the JPEG XL file.
destinationPath string
The path of the JPEG file, which is created or replaced once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
cancellationToken CancellationToken
The token to monitor for cancellation requests.
Returns

Task A task that completes when the file is written.

Exceptions
ArgumentNullException
jpegXlPath or destinationPath is null.
ArgumentException
jpegXlPath or destinationPath is empty.

TryReconstructJpeg overloads

TryReconstructJpeg(Stream, Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.

public static bool TryReconstructJpeg(Stream jpegXl, Stream destination, JpegXlTranscodeOptions? options = null)
Parameters
jpegXl Stream
The JPEG XL file.
destination Stream
Receives the JPEG file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Returns

bool false when the file does not hold the data that rebuild a JPEG file: nothing is written.

Exceptions
ArgumentNullException
jpegXl or destination is null.
ArgumentException
jpegXl is not readable, or destination is not writable.

TryReconstructJpeg(ReadOnlySpan<byte>, Stream, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.

public static bool TryReconstructJpeg(ReadOnlySpan<byte> jpegXl, Stream destination, JpegXlTranscodeOptions? options = null)
Parameters
jpegXl ReadOnlySpan<byte>
The JPEG XL file.
destination Stream
Receives the JPEG file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Returns

bool false when the file does not hold the data that rebuild a JPEG file: nothing is written.

Exceptions
ArgumentNullException
destination is null.
ArgumentException
destination is not writable.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file.
InvalidImageContentException
The file is malformed or truncated, or its reconstruction data do not match its image.
ImageResourceLimitException
A configured limit is exceeded.

TryReconstructJpeg(string, string, JpegXlTranscodeOptions?)

JpegXlTranscoder.cs

Rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.

public static bool TryReconstructJpeg(string jpegXlPath, string destinationPath, JpegXlTranscodeOptions? options = null)
Parameters
jpegXlPath string
The path of the JPEG XL file.
destinationPath string
The path of the JPEG file, which is created or replaced once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
Returns

bool false when the file does not hold the data that rebuild a JPEG file: nothing is written.

Exceptions
ArgumentNullException
jpegXlPath or destinationPath is null.
ArgumentException
jpegXlPath or destinationPath is empty.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file.
InvalidImageContentException
The file is malformed or truncated, or its reconstruction data do not match its image.
ImageResourceLimitException
A configured limit is exceeded.

TryReconstructJpegAsync(Stream, Stream, JpegXlTranscodeOptions?, CancellationToken)

JpegXlTranscoder.cs

Asynchronously rebuilds the JPEG file a JPEG XL file was made from, byte for byte, when the file holds the data that rebuild it.

public static Task<bool> TryReconstructJpegAsync(Stream jpegXl, Stream destination, JpegXlTranscodeOptions? options = null, CancellationToken cancellationToken = default)

Parameters

jpegXl Stream
The JPEG XL file.
destination Stream
Receives the JPEG file, once it is whole.
options JpegXlTranscodeOptions?
The options, or null for the default ones.
cancellationToken CancellationToken
The token to monitor for cancellation requests.

Returns

Task<bool> false when the file does not hold the data that rebuild a JPEG file: nothing is written.

Exceptions

ArgumentNullException
jpegXl or destination is null.
ArgumentException
jpegXl is not readable, or destination is not writable.