net.sourceforge.javaflacencoder

Class FLACEncoder

java.lang.Object

net.sourceforge.javaflacencoder.FLACEncoder

public class FLACEncoder
extends 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, with the exception that step 4 must not be called while a concurrent step 6 is executing(as in threaded mode). See related method documentation for info on concurrent use) (note: steps 4,5, and 6 may be done repeatedly, in any order, with the exception that step 4 must not be called while a concurrent step 6 is executing(as in threaded mode). See related method documentation for info on concurrent use. For step 7, see the documentation for the encodeSamples(...) methods' "end" parameter)

Author:

Preston Lacey

Field Summary

Fields

Modifier and Type	Field and Description
ReentrantLock	streamLock

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	addSamples(int[] samples, int count) Add samples to the encoder, so they may then be encoded.
protected 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.
int	getThreadCount() Get the number of threads this FLACEncoder is currently set to use.
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.
boolean	setThreadCount(int count) Tell encoder how many threads to use for encoding.
int	t_encodeSamples(int inCount, boolean end, int blockingCount) 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

Field Detail

streamLock

public final ReentrantLock streamLock

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

setThreadCount

public boolean setThreadCount(int count)

Tell encoder how many threads to use for encoding. More threads than this will exist, but only the given amount should be in a running state at any moment(the other threads are simply manager threads, waiting for encoding-threads to end). A special case is setting "count" to zero; this will tell the encoder not to use internal threads at all, and all encoding will be done with the main thread. Otherwise, any encode methods will return while the encode actually takes place in a separate thread.

Parameters:

count - Number of encoding threads to use. Count > 0 means use that many independent encoding threads, count == 0 means encode in main thread, count < 0 is ignored.

Returns:

boolean value represents whether requested count was applied or not. This may be false if a FLAC stream is currently opened.

getThreadCount

public int getThreadCount()

Get the number of threads this FLACEncoder is currently set to use.

Returns:

number of threads this encoder is currently set to use.

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. This must not be called while an encodeSamples(...) is active, or while encoding threads are active. If using threaded mode, use a blocking-count of zero in t_encodeSamples(...)to ensure the underlying encoding threads have finished before calling this method.

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. Calling this method clears any data stored by this encoder. 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 final 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 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:

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

addSamples

public void 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.

blockFinished

protected 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 inCount,
                           boolean end,
                           int blockingCount)
                    throws 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. If getThreadCount() ≤ 0, simply calls the non-threaded version, encodeSamples(...), and blocks until it returns.

Parameters:

inCount - number of samples to attempt to encode. Actual number encoded may be greater or less if count does not end on a block boundary. If "end" is false, we may set this value to something absurdly high, such as Integer.MAX_VALUE to ensure all available, full blocks are encoded.

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.

blockingCount - value is used for flow-control into this encoder. This method will block until fewer than the given number of blocks remain queued for encoding.

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:

IOException - if there was an error writing the results to output stream.

encodeSamples

public int encodeSamples(int count,
                         boolean end)
                  throws 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:

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, or a flac stream is already opened.

Parameters:

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