Struct hound::WavWriter

pub struct WavWriter<W> where
    W: Write + Seek,  { /* private fields */ }

A writer that accepts samples and writes the WAVE format.

The writer needs a WavSpec that describes the audio properties. Then samples can be written with write_sample. Channel data is interleaved. The number of samples written must be a multiple of the number of channels. After all samples have been written, the file must be finalized. This can be done by calling finalize. If finalize is not called, the file will be finalized upon drop. However, finalization may fail, and without calling finalize, such a failure cannot be observed.

Implementations

impl<W> WavWriter<W> where
    W: Write + Seek, 

pub fn new(writer: W, spec: WavSpec) -> Result<WavWriter<W>>

Creates a writer that writes the WAVE format to the underlying writer.

The underlying writer is assumed to be at offset 0. WavWriter employs no buffering internally. It is recommended to wrap the writer in a BufWriter to avoid too many write calls. The create() constructor does this automatically.

This writes parts of the header immediately, hence a Result is returned.

pub fn write_sample<S: Sample>(&mut self, sample: S) -> Result<()>

Writes a single sample for one channel.

WAVE interleaves channel data, so the channel that this writes the sample to depends on previous writes. This will return an error if the sample does not fit in the number of bits specified in the WavSpec.

pub fn get_i16_writer<'s>(
    &'s mut self,
    num_samples: u32
) -> SampleWriter16<'s, W>

Create an efficient writer that writes 16-bit integer samples only.

When it is known what the kind of samples will be, many dynamic checks can be omitted. Furthermore, this writer employs buffering internally, which allows omitting return value checks except on flush. The internal buffer will be sized such that exactly num_samples samples can be written to it, and the buffer is recycled across calls to get_i16_writer() if the previous buffer was sufficiently large.

Panics

Panics if the spec does not match a 16 bits per sample integer format.

Attempting to write more than num_samples samples to the writer will panic too.

pub fn flush(&mut self) -> Result<()>

Updates the WAVE header and flushes the underlying writer.

Flush writes the WAVE header to the underlying writer to make the written bytes a valid wav file, and then flushes the writer. It is still possible to write more samples after flushing.

Flush can be used for “checkpointing”. Even if after the flush there is an IO error or the writing process dies, the file can still be read by a compliant decoder up to the last flush.

Note that if the number of samples written is not a multiple of the channel count, the intermediate wav file will not be valid. In that case flush() will still flush the data and write the (invalid) wav file, but Error::UnfinishedSample will be returned afterwards.

It is not necessary to call finalize() directly after flush(), if no samples have been written after flushing.

pub fn finalize(self) -> Result<()>

Updates the WAVE header (which requires knowing all samples).

This method must be called after all samples have been written. If it is not called, the destructor will finalize the file, but any errors that occur in the process cannot be observed in that manner.

pub fn spec(&self) -> WavSpec

Returns information about the WAVE file being written.

This is the same spec that was passed to WavWriter::new(). For a writer constructed with WavWriter::new_append() or WavWriter::append(), this method returns the spec of the file being appended to.

pub fn duration(&self) -> u32

Returns the duration of the file written so far, in samples.

The duration is independent of the number of channels. It is expressed in units of samples. The duration in seconds can be obtained by dividing this number by the sample rate.

pub fn len(&self) -> u32

Returns the number of samples in the file written so far.

The length of the file is its duration (in samples) times the number of channels.

impl WavWriter<BufWriter<File>>

pub fn create<P: AsRef<Path>>(
    filename: P,
    spec: WavSpec
) -> Result<WavWriter<BufWriter<File>>>

Creates a writer that writes the WAVE format to a file.

This is a convenience constructor that creates the file, wraps it in a BufWriter, and then constructs a WavWriter from it. The file will be overwritten if it exists.

pub fn append<P: AsRef<Path>>(filename: P) -> Result<WavWriter<BufWriter<File>>>

Creates a writer that appends samples to an existing file.

This is a convenience constructor that opens the file in append mode, reads its header using a buffered reader, and then constructs an appending WavWriter that writes to the file using a BufWriter.

See WavWriter::new_append() for more details about append behavior.

impl<W> WavWriter<W> where
    W: Read + Write + Seek, 

pub fn new_append(writer: W) -> Result<WavWriter<W>>

Creates a writer that appends samples to an existing file stream.

This first reads the existing header to obtain the spec, then seeks to the end of the writer. The writer then appends new samples to the end of the stream.

The underlying writer is assumed to be at offset 0.

If the existing file includes a fact chunk, it will not be updated after appending, and hence become outdated. For files produced by Hound this is not an issue, because Hound never writes a fact chunk. For all the formats that Hound can write, the fact chunk is redundant.

Trait Implementations

impl<W> Drop for WavWriter<W> where
    W: Write + Seek, 

fn drop(&mut self)

Executes the destructor for this type.