krut.KRUT_Recording
Class Sampler

java.lang.Object
  java.lang.Thread
      krut.KRUT_Recording.Sampler

All Implemented Interfaces:

java.lang.Runnable

public class Sampler
extends java.lang.Thread

The audio sampler records sound from a DataLine obtained from the AudioSystem. The sound is recorded by obtaining a series of samples buffered in the DataLine and saving them through an OutputStream into a file. Before the samples are saved, a synchronization check (optional) is performed, and if there has been loss of sound, the existing series of samples are "stretched" through an algorithm explained in the source comments, until sync with the system-clock is re-established.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

java.io.File	audioFile The file used for saving the audio data.
int	channels The number of recording channels.
int	countTimesAhead IMPORTANT: countTimesAhead should always be 0, or there can be a situation where the sampler can no longer "catch up" with the clock.
int	countTimesLag This is the counter for how many times the sampler should wait before correcting a delayed sample.
float	frequency The recording frequency.
int	maxAhead The maximum ahead times in parts of a second, like this: maxAhead = 50 gives the max ahead 1/50 s = 20ms.
int	maxLag The maximum lag times in parts of a second, like this: maxLag = 50 gives the max lag 1/50 s = 20ms.
SaveFileChooser	mySaveQuery It is necessary for the Sampler to have access to a SaveFileChooser, because the Sampler needs to use the getNextFile() method both in init() and in finished().
boolean	recording recording is used to flag if the Sampler is recording.
int	sampleSize The sample size in bits.
long	sleepTime The time the sampler sleeps between each time emptying the buffer, in milliseconds.
float	speed This is a measure of the speed the sound should be played back with.
boolean	stopped stopped is a flag to tell the Sampler if it should record or not.
boolean	syncAudio syncAudio is a flag to tell the sampler if it should sync audio, whenever it misses frames, or just continue recording.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Sampler()
Creates a new instance of Sampler Calling this constructor will create a Sampler that uses an output File with the default filename given by the private parameter defaultFileName.

Sampler(java.lang.String fileName)
Creates a new instance of Sampler Calling this constructor will create a Sampler that uses an output File with the specified filename.

Method Summary

void	finish() Finish up, writing the final audio file from the temporary file already created.
void	hold() Used to sync audio.
void	init() This method sets up all the input streams and output streams that are used in the recording.
void	run() Main working method.
boolean	setAudioFile(java.lang.String fileName) Change the name of the final audio output file to.
void	setSyncTime(long syncTime) Set the syncTime for the run() method This MUST be done before wakeUp() is called to start the recording.
void	stopRecording() Stops the recording.
void	wakeUp() Wakes up threads waiting for the sampler.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

frequency

public float frequency

The recording frequency. Changing this value here may have no effect, since it may be changed by the user before recording starts. Is changed from Run_KRUT.createSampler().

sampleSize

public int sampleSize

The sample size in bits. Changing this value here may have no effect, since it may be changed by the user before recording starts. Is changed from Run_KRUT.createSampler().

channels

public int channels

The number of recording channels. Changing this value here may have no effect, since it may be changed by the user before recording starts. Is changed from Run_KRUT.createSampler().

audioFile

public java.io.File audioFile

The file used for saving the audio data. If the audiofile is changed, init() needs to be called afterwards.

recording

public boolean recording

recording is used to flag if the Sampler is recording.

stopped

public boolean stopped

stopped is a flag to tell the Sampler if it should record or not.

syncAudio

public boolean syncAudio

syncAudio is a flag to tell the sampler if it should sync audio, whenever it misses frames, or just continue recording.

countTimesLag

public int countTimesLag

This is the counter for how many times the sampler should wait before correcting a delayed sample. This value can be changed here, and another, private integer copies this value on each loop (the run loop).

countTimesAhead

public int countTimesAhead

IMPORTANT: countTimesAhead should always be 0, or there can be a situation where the sampler can no longer "catch up" with the clock. It is kept for facilitating (?) future development.

speed

public float speed

This is a measure of the speed the sound should be played back with. It is playbackFPS/recordingFPS. This parameter is changed by Run_KRUT.checkInited.

mySaveQuery

public SaveFileChooser mySaveQuery

It is necessary for the Sampler to have access to a SaveFileChooser, because the Sampler needs to use the getNextFile() method both in init() and in finished(). This parameter will be updated by Run_KRUT as soon as the global SaveFileChooser is initiated.

sleepTime

public long sleepTime

The time the sampler sleeps between each time emptying the buffer, in milliseconds.

maxLag

public int maxLag

The maximum lag times in parts of a second, like this: maxLag = 50 gives the max lag 1/50 s = 20ms.

maxAhead

public int maxAhead

The maximum ahead times in parts of a second, like this: maxAhead = 50 gives the max ahead 1/50 s = 20ms.

Constructor Detail

Sampler

public Sampler(java.lang.String fileName)

Creates a new instance of Sampler Calling this constructor will create a Sampler that uses an output File with the specified filename. The file name can be changed by a call to the setAudioFile method.

Parameters:

fileName - The file name of the audio file that is created by this Sampler.

Sampler

public Sampler()

Creates a new instance of Sampler Calling this constructor will create a Sampler that uses an output File with the default filename given by the private parameter defaultFileName. The file name can be changed by a call to the setAudioFile method.

Method Detail

init

public void init()

This method sets up all the input streams and output streams that are used in the recording. This method should be called every time a parameter affecting those streams has been changed (eg. sampling frequency). This method does not have to be called for just a change in save file name, since a temporary buffer file is used for output during recording. The method is called by the run method once every time at the start of recording.

stopRecording

public void stopRecording()

Stops the recording. To make sure the recording has stopped, the recording flag can be checked after calling this method. eg. while(thisSampler.recording) thisSampler.hold(); It's not a good idea to call this method just 'stop()' because stop() is a (deprecated) method of the class 'Thread'. And we don't want to override this method. Before this method is called, stopped should be set true by the user. This method must be called to stop the recording! To start recording, stopped must be set to false again, and wakeUp() must be called.

setSyncTime

public void setSyncTime(long syncTime)

Set the syncTime for the run() method This MUST be done before wakeUp() is called to start the recording. If not, the audio will be extremely out of sync.

Parameters:

syncTime - The time to wait (in millis) between each audio sync check.

hold

public void hold()

Used to sync audio. Other threads may call this method, and are then woken when all audio recording is finished. The recording flag must be checked in order to safely determine if recording is running upon return from this method.

wakeUp

public void wakeUp()

Wakes up threads waiting for the sampler. This is used to start the actual recording, if stopped is set to false before calling this method. Also syncTime MUST be set, by calling setSyncTime, before wakeUp() is called. This method is called once when all audio data are written to the OutputStream.

run

public void run()

Main working method. Checks how much data is available in the line and then calls getSamples() to get them. It then sleeps for sleepTime milliseconds, and repeats until the line is closed.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

setAudioFile

public boolean setAudioFile(java.lang.String fileName)

Change the name of the final audio output file to. Since the output file will always be a .wav file, the file name should end with .wav, but this is not controlled. It usually shouldn't matter for any practical purposes. This method can actually be called while recording is in progress (recording writes to a temporary file, named by the parameter bufferFileName), but calling it while writing to the actual output file will cause it to block until the writing is finished (writing to output file is done by the method finish).

Parameters:

fileName - The name of the file that should be created by this Sampler.

Returns:

true if the file was successfully created, false if not.

finish

public void finish()

Finish up, writing the final audio file from the temporary file already created.