javaFlacEncoder
Class FLACEncoder

java.lang.Object
  javaFlacEncoder.FLACEncoder

public class FLACEncoder
extends java.lang.Object

This class defines a FLAC Encoder with a simple interface for enabling FLAC encoding support in an application. This class is appropriate for use in the case where you have raw pcm audio samples that you wish to encode. Currently, fixed-blocksize only is implemented, and the "Maximum Block Size" set in the StreamConfiguration object is used as the actual block size.


An encoding process is simple, and should follow these steps:

1) Set StreamConfiguration to appropriate values. After a stream is opened, this must not be altered until the stream is closed.
2) Set FLACOutputStream, object to write results to.
3) Open FLAC Stream
4) Set EncodingConfiguration(if defaults are insufficient).
5) Add samples to encoder
6) Encode Samples
7) Close stream
(note: steps 4,5, and 6 may be done repeatedly, in any order. However, see related method documentation for info on concurrent use. For step 7, see the documentation for the encodeSamples(...) methods' "end" parameter)

Author:

Preston Lacey

Constructor Summary

FLACEncoder()
Constructor which creates a new encoder object with the default settings.

Method Summary

boolean	addSamples(int[] samples, int count) Add samples to the encoder, so they may then be encoded.
void	blockFinished(BlockEncodeRequest ber) Notify the encoder that a BlockEncodeRequest has finished, and is now ready to be written to file.
void	clear() Clear all samples stored by this object, but not yet encoded.
int	encodeSamples(int count, boolean end) Attempt to Encode a certain number of samples.
int	fullBlockSamplesAvailableToEncode() Get number of samples which are ready to encode.
void	openFLACStream() Begin a new FLAC stream.
int	samplesAvailableToEncode() Get number of samples that are available to encode.
boolean	setEncodingConfiguration(EncodingConfiguration ec) Set the encoding configuration to that specified.
void	setOutputStream(FLACOutputStream fos) Set the output stream to use.
boolean	setStreamConfiguration(StreamConfiguration sc) Set the stream configuration to that specified.
int	t_encodeSamples(int count, boolean end) Attempt to Encode a certain number of samples(threaded version).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FLACEncoder

public FLACEncoder()

Constructor which creates a new encoder object with the default settings. The StreamConfiguration should be reset to match the audio used and an output stream set, but the default EncodingConfiguration should be ok for most purposes. When using threaded encoding, the default number of threads used is equal to FLACEncoder.MAX_THREADED_FRAMES.

Method Detail

setEncodingConfiguration

public boolean setEncodingConfiguration(EncodingConfiguration ec)

Set the encoding configuration to that specified. The given encoding configuration is not stored by this object, but instead copied. This is to prevent the alteration of the config during an encode process.

Parameters:

ec - EncodingConfiguration to use.

Returns:

true if the configuration was altered; false if the configuration cannot be altered(such as if another thread is currently encoding).

setStreamConfiguration

public boolean setStreamConfiguration(StreamConfiguration sc)

Set the stream configuration to that specified. The given stream configuration is not stored by this object, but instead copied. This is to prevent the alteration of the config during an encode process. This method must not be called in the middle of a stream, stream contents may become invalid. A call to setStreamConfiguration() should be followed next by setting the output stream if not yet done, and then calling openFLACStream();

Parameters:

sc - StreamConfiguration to use.

Returns:

true if the configuration was altered; false if the configuration cannot be altered(such as if another thread is currently encoding).

clear

public void clear()

Clear all samples stored by this object, but not yet encoded. Should be called between encoding differrent streams(before more samples are added), unless you desire to keep unencoded samples. This does NOT reset or close the active stream.

openFLACStream

public void openFLACStream()
                    throws java.io.IOException

Begin a new FLAC stream. Prior to calling this, you must have already set the StreamConfiguration and the output stream, both of which must not change until encoding is finished and the stream is closed. If this FLACEncoder object has already been used to encode a stream, unencoded samples may still be stored. Use clear() to dump them prior to calling this method(if clear() not called, and samples are instead retained, the StreamConfiguration must NOT have changed from the prior stream.

Throws:

java.io.IOException - if there is an error writing the headers to output.

addSamples

public boolean addSamples(int[] samples,
                          int count)

Add samples to the encoder, so they may then be encoded. This method uses breaks the samples into blocks, which will then be made available to encode.

Parameters:

samples - Array holding the samples to encode. For all multi-channel audio, the samples must be interleaved in this array. For example, with stereo: sample 0 will belong to the first channel, 1 the second, 2 the first, 3 the second, etc. Samples are interpreted according to the current configuration(for things such as channel and bits-per-sample).

count - Number of interchannel samples to add. For example, with stero: if this is 4000, then "samples" must contain 4000 left samples and 4000 right samples, interleaved in the array.

Returns:

true if samples were added, false otherwise. A value of false may result if "count" is set to a size that is too large to be valid with the given array and current configuration.

blockFinished

public void blockFinished(BlockEncodeRequest ber)

Notify the encoder that a BlockEncodeRequest has finished, and is now ready to be written to file. The encoder expects that these requests come back in the same order the encoder sent them out. This is intended to be used in threading mode only at the moment(sending them to a BlockThreadManager object)

Parameters:

ber - BlockEncodeRequest that is ready to write to file.

t_encodeSamples

public int t_encodeSamples(int count,
                           boolean end)
                    throws java.io.IOException

Attempt to Encode a certain number of samples(threaded version). Encodes as close to count as possible. Uses multiple threads to speed up encoding.

Parameters:

count - number of samples to attempt to encode. Actual number encoded may be greater or less if count does not end on a block boundary.

end - true to finalize stream after encode, false otherwise. If set to true, and return value is greater than or equal to given count, no more encoding must be attempted until a new stream is began.

Returns:

number of samples encoded. This may be greater or less than requested count if count does not end on a block boundary. This is NOT an error condition. If end was set "true", and returned count is less than requested count, then end was NOT done, if you still wish to end stream, call this again with end true and a count of of <= samplesAvailableToEncode()

Throws:

java.io.IOException - if there was an error writing the results to file.

encodeSamples

public int encodeSamples(int count,
                         boolean end)
                  throws java.io.IOException

Attempt to Encode a certain number of samples. Encodes as close to count as possible.

Parameters:

count - number of samples to attempt to encode. Actual number encoded may be greater or less if count does not end on a block boundary.

end - true to finalize stream after encode, false otherwise. If set to true, and return value is greater than or equal to given count, no more encoding must be attempted until a new stream is began.

Returns:

number of samples encoded. This may be greater or less than requested count if count does not end on a block boundary. This is NOT an error condition. If end was set "true", and returned count is less than requested count, then end was NOT done, if you still wish to end stream, call this again with end true and a count of of <= samplesAvailableToEncode()

Throws:

java.io.IOException - if there was an error writing the results to file.

fullBlockSamplesAvailableToEncode

public int fullBlockSamplesAvailableToEncode()

Get number of samples which are ready to encode. More samples may exist in the encoder as a partial block. Use samplesAvailableToEncode() if you wish to include those as well.

Returns:

number of samples in full blocks, ready to encode.

samplesAvailableToEncode

public int samplesAvailableToEncode()

Get number of samples that are available to encode. This includes samples which are in a partial block(and so would only be written if "end" was set true in encodeSamples(int count,boolean end);

Returns:

number of samples availble to encode.

setOutputStream

public void setOutputStream(FLACOutputStream fos)

Set the output stream to use. This must not be called while an encode process is active.

Parameters:

fos - output stream to use. This must not be null.