Class SoundFileWriter

Namespace

NAudio.SoundFile

Assembly

NAudio.SoundFile.dll

Encodes audio to any format libsndfile can write (WAV, AIFF, FLAC, Ogg/Vorbis, Opus, MP3, …). Mirrors WaveFileWriter: it is a Stream you push source-format bytes into, with static helpers that pump an entire IWaveProvider.

public sealed class SoundFileWriter : Stream, IAsyncDisposable, IDisposable

Inheritance

object

MarshalByRefObject

Stream

SoundFileWriter

Implements

IAsyncDisposable

IDisposable

Inherited Members

Stream.Null

Stream.BeginRead(byte[], int, int, AsyncCallback, object)

Stream.BeginWrite(byte[], int, int, AsyncCallback, object)

Stream.Close()

Stream.CopyTo(Stream)

Stream.CopyTo(Stream, int)

Stream.CopyToAsync(Stream)

Stream.CopyToAsync(Stream, int)

Stream.CopyToAsync(Stream, int, CancellationToken)

Stream.CopyToAsync(Stream, CancellationToken)

Stream.Dispose()

Stream.DisposeAsync()

Stream.EndRead(IAsyncResult)

Stream.EndWrite(IAsyncResult)

Stream.FlushAsync()

Stream.FlushAsync(CancellationToken)

Stream.Read(Span<byte>)

Stream.ReadAsync(byte[], int, int)

Stream.ReadAsync(byte[], int, int, CancellationToken)

Stream.ReadAsync(Memory<byte>, CancellationToken)

Stream.ReadAtLeast(Span<byte>, int, bool)

Stream.ReadAtLeastAsync(Memory<byte>, int, bool, CancellationToken)

Stream.ReadByte()

Stream.ReadExactly(byte[], int, int)

Stream.ReadExactly(Span<byte>)

Stream.ReadExactlyAsync(byte[], int, int, CancellationToken)

Stream.ReadExactlyAsync(Memory<byte>, CancellationToken)

Stream.Synchronized(Stream)

Stream.WriteAsync(byte[], int, int)

Stream.WriteAsync(byte[], int, int, CancellationToken)

Stream.WriteAsync(ReadOnlyMemory<byte>, CancellationToken)

Stream.WriteByte(byte)

Stream.CanTimeout

Stream.ReadTimeout

Stream.WriteTimeout

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.InitializeLifetimeService()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The input WaveFormat must be 16-bit PCM or 32-bit IEEE float — the two container types NAudio pipelines naturally produce. libsndfile transcodes that into the chosen output subtype (clipping out-of-range float by default; see Clipping). Which codecs are available depends on the system libsndfile build — see SoundFileCapabilities.

Constructors

SoundFileWriter(Stream, WaveFormat, SoundFileMajorFormat, SoundFileWriterOptions)

Creates a writer to a stream in an explicit format. The stream is not disposed by the writer (the caller owns it). Streamed formats (FLAC/Ogg/Opus/MP3) work on non-seekable streams; WAV/AIFF need a seekable stream to back-patch their header.

public SoundFileWriter(Stream outStream, WaveFormat sourceFormat, SoundFileMajorFormat major, SoundFileWriterOptions options = null)

Parameters

outStream Stream

Destination stream.

sourceFormat WaveFormat

Format of the bytes you will write (16-bit PCM or 32-bit IEEE float).

major SoundFileMajorFormat

The container / codec to produce.

options SoundFileWriterOptions

Encoder options, or null for defaults.

Exceptions

ArgumentException

The stream can't satisfy the format, or libsndfile rejects it.

NotSupportedException

sourceFormat is not 16-bit PCM or 32-bit float.

SoundFileWriter(string, WaveFormat)

Creates a writer to a file, choosing the format from the path's extension (e.g. .flac, .ogg, .opus, .wav).

public SoundFileWriter(string path, WaveFormat sourceFormat)

Parameters

path string

Output path.

sourceFormat WaveFormat

Format of the bytes you will write (16-bit PCM or 32-bit IEEE float).

Exceptions

ArgumentException

The extension is unknown, or libsndfile rejects the format.

NotSupportedException

sourceFormat is not 16-bit PCM or 32-bit float.

SoundFileWriter(string, WaveFormat, SoundFileMajorFormat, SoundFileWriterOptions)

Creates a writer to a file in an explicit format.

public SoundFileWriter(string path, WaveFormat sourceFormat, SoundFileMajorFormat major, SoundFileWriterOptions options = null)

Parameters

path string

Output path.

sourceFormat WaveFormat

Format of the bytes you will write (16-bit PCM or 32-bit IEEE float).

major SoundFileMajorFormat

The container / codec to produce.

options SoundFileWriterOptions

Encoder options, or null for defaults.

Exceptions

ArgumentException

libsndfile rejects the format/rate/channel combination.

NotSupportedException

sourceFormat is not 16-bit PCM or 32-bit float.

Properties

CanRead

When overridden in a derived class, gets a value indicating whether the current stream supports reading.

public override bool CanRead { get; }

Property Value

bool

true if the stream supports reading; otherwise, false.

CanSeek

When overridden in a derived class, gets a value indicating whether the current stream supports seeking.

public override bool CanSeek { get; }

Property Value

bool

true if the stream supports seeking; otherwise, false.

CanWrite

When overridden in a derived class, gets a value indicating whether the current stream supports writing.

public override bool CanWrite { get; }

Property Value

bool

true if the stream supports writing; otherwise, false.

Length

Number of source bytes accepted so far.

public override long Length { get; }

Property Value

long

Position

When overridden in a derived class, gets or sets the position within the current stream.

public override long Position { get; set; }

Property Value

long

The current position within the stream.

Exceptions

IOException

An I/O error occurs.

NotSupportedException

The stream does not support seeking.

ObjectDisposedException

Methods were called after the stream was closed.

WaveFormat

The input format the writer was constructed with.

public WaveFormat WaveFormat { get; }

Property Value

WaveFormat

Methods

CreateSoundFile(string, IWaveProvider)

Encodes an entire IWaveProvider to a file, choosing the format from the path's extension. The source must end (return 0 from Read) or the file grows indefinitely.

public static void CreateSoundFile(string path, IWaveProvider source)

Parameters

path string

Output path; extension selects the format.

source IWaveProvider

The audio to encode.

CreateSoundFile(string, IWaveProvider, SoundFileMajorFormat, SoundFileWriterOptions)

Encodes an entire IWaveProvider to a file in an explicit format. The source must end (return 0 from Read).

public static void CreateSoundFile(string path, IWaveProvider source, SoundFileMajorFormat major, SoundFileWriterOptions options)

Parameters

path string

Output path.

source IWaveProvider

The audio to encode.

major SoundFileMajorFormat

The container / codec to produce.

options SoundFileWriterOptions

Encoder options, or null for defaults.

CreateSoundFile16(string, ISampleProvider)

Encodes a 16-bit version of an ISampleProvider to a file, choosing the format from the path's extension.

public static void CreateSoundFile16(string path, ISampleProvider source)

Parameters

path string

Output path; extension selects the format.

source ISampleProvider

The sample source.

Dispose(bool)

Releases the unmanaged resources used by the Stream and optionally releases the managed resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

Flush()

When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device.

public override void Flush()

Exceptions

IOException

An I/O error occurs.

FromRawFormat(Stream, WaveFormat, int, SoundFileWriterOptions)

Creates a writer to a stream using a raw libsndfile format bitfield. Advanced escape hatch.

public static SoundFileWriter FromRawFormat(Stream outStream, WaveFormat sourceFormat, int rawFormat, SoundFileWriterOptions options = null)

Parameters

outStream Stream

Destination stream.

sourceFormat WaveFormat

Format of the bytes you will write (16-bit PCM or 32-bit IEEE float).

rawFormat int

A libsndfile SF_FORMAT_* bitfield (major | subtype).

options SoundFileWriterOptions

Encoder options, or null for defaults.

Returns

SoundFileWriter

A new writer.

FromRawFormat(string, WaveFormat, int, SoundFileWriterOptions)

Creates a writer to a file using a raw libsndfile format bitfield. Advanced escape hatch for formats this library's enums don't model.

public static SoundFileWriter FromRawFormat(string path, WaveFormat sourceFormat, int rawFormat, SoundFileWriterOptions options = null)

Parameters

path string

Output path.

sourceFormat WaveFormat

Format of the bytes you will write (16-bit PCM or 32-bit IEEE float).

rawFormat int

A libsndfile SF_FORMAT_* bitfield (major | subtype).

options SoundFileWriterOptions

Encoder options, or null for defaults.

Returns

SoundFileWriter

A new writer.

Read(byte[], int, int)

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

public override int Read(byte[] buffer, int offset, int count)

Parameters

buffer byte[]

An array of bytes. When this method returns, the buffer contains the specified byte array with the values between offset and (offset + count - 1) replaced by the bytes read from the current source.

offset int

The zero-based byte offset in buffer at which to begin storing the data read from the current stream.

count int

The maximum number of bytes to be read from the current stream.

Returns

int

The total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if count is 0 or the end of the stream has been reached.

Exceptions

ArgumentException

The sum of offset and count is larger than the buffer length.

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or count is negative.

IOException

An I/O error occurs.

NotSupportedException

The stream does not support reading.

ObjectDisposedException

Methods were called after the stream was closed.

Seek(long, SeekOrigin)

When overridden in a derived class, sets the position within the current stream.

public override long Seek(long offset, SeekOrigin origin)

Parameters

offset long

A byte offset relative to the origin parameter.

origin SeekOrigin

A value of type SeekOrigin indicating the reference point used to obtain the new position.

Returns

long

The new position within the current stream.

Exceptions

IOException

An I/O error occurs.

NotSupportedException

The stream does not support seeking, such as if the stream is constructed from a pipe or console output.

ObjectDisposedException

Methods were called after the stream was closed.

SetLength(long)

When overridden in a derived class, sets the length of the current stream.

public override void SetLength(long value)

Parameters

value long

The desired length of the current stream in bytes.

Exceptions

IOException

An I/O error occurs.

NotSupportedException

The stream does not support both writing and seeking, such as if the stream is constructed from a pipe or console output.

ObjectDisposedException

Methods were called after the stream was closed.

Write(byte[], int, int)

When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.

public override void Write(byte[] buffer, int offset, int count)

Parameters

buffer byte[]

An array of bytes. This method copies count bytes from buffer to the current stream.

offset int

The zero-based byte offset in buffer at which to begin copying bytes to the current stream.

count int

The number of bytes to be written to the current stream.

Exceptions

ArgumentException

The sum of offset and count is greater than the buffer length.

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

offset or count is negative.

IOException

An I/O error occurred, such as the specified file cannot be found.

NotSupportedException

The stream does not support writing.

ObjectDisposedException

Write(byte[], int, int) was called after the stream was closed.

Write(ReadOnlySpan<byte>)

Appends source-format bytes. Sub-frame remainders are carried over between calls, so callers may write arbitrary chunk sizes.

public override void Write(ReadOnlySpan<byte> buffer)

Parameters

buffer ReadOnlySpan<byte>

Bytes in the constructor's input format.

Exceptions

SoundFileException

The encoder failed.

WriteSamples(ReadOnlySpan<float>)

Writes 32-bit float samples (interleaved by channel). Works regardless of the declared input format; libsndfile converts to the output subtype. Sample count should be a multiple of the channel count.

public void WriteSamples(ReadOnlySpan<float> samples)

Parameters

samples ReadOnlySpan<float>

Interleaved float samples.

Exceptions

SoundFileException

The encoder failed.

WriteSoundFileToStream(Stream, IWaveProvider, SoundFileMajorFormat, SoundFileWriterOptions)

Encodes an entire IWaveProvider to a stream. The stream is left open; the source must end (return 0 from Read).

public static void WriteSoundFileToStream(Stream outStream, IWaveProvider source, SoundFileMajorFormat major, SoundFileWriterOptions options)

Parameters

outStream Stream

Destination stream.

source IWaveProvider

The audio to encode.

major SoundFileMajorFormat

The container / codec to produce.

options SoundFileWriterOptions

Encoder options, or null for defaults.