marytts.unitselection.data

Class TimelineReader

java.lang.Object

marytts.unitselection.data.TimelineReader

Direct Known Subclasses:

HnmTimelineReader, LPCTimelineReader, MCepTimelineReader

public class TimelineReader
extends Object

The TimelineReader class provides an interface to read regularly or variably spaced datagrams from a Timeline data file in Mary format.

Author:

sacha, marc

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TimelineReader.IdxField Simple helper class to read the index fields in a timeline.
static class	TimelineReader.Index Simple helper class to read the index part of a timeline file.
static class	TimelineReader.ProcHeader Simple helper class to load the processing header.

Field Summary

Fields

Modifier and Type	Field and Description
protected int	datagramsBytePos
protected TimelineReader.Index	idx
protected MaryHeader	maryHdr
protected long	numDatagrams
protected TimelineReader.ProcHeader	procHdr
protected int	sampleRate
protected int	timeIdxBytePos
protected long	totalDuration The total duration of the timeline data, in samples.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TimelineReader() Only subclasses can instantiate a TimelineReader object that doesn't call load(String).
	TimelineReader(String fileName) Construct a timeline from the given file name.
	TimelineReader(String fileName, boolean tryMemoryMapping) Construct a timeline from the given file name.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	computeTotalDuration() Compute the total duration of a timeline.
protected Pair<ByteBuffer,Long>	getByteBufferAtTime(long targetTimeInSamples) This method produces a new byte buffer whose current position represents the requested positionInFile.
Datagram	getDatagram(long targetTimeInSamples) Get a single datagram from a particular time location, given in the timeline's sampling rate.
Datagram	getDatagram(long targetTimeInSamples, int reqSampleRate) Get a single datagram from a particular time location.
Datagram[]	getDatagrams(long targetTimeInSamples, int number, int reqSampleRate, long[] returnOffset) Get a given number of datagrams from a particular time location, and return the time offset between the time request and the actual location of the first returned datagram.
Datagram[]	getDatagrams(long targetTimeInSamples, long timeSpanInSamples) Get a given number of datagrams from a particular time location.
Datagram[]	getDatagrams(long targetTimeInSamples, long timeSpanInSamples, int reqSampleRate) Get the datagrams spanning a particular time range from a particular time location.
Datagram[]	getDatagrams(long targetTimeInSamples, long timeSpanInSamples, int reqSampleRate, long[] returnOffset) Get the datagrams spanning a particular time range from a particular time location, and return the time offset between the time request and the actual location of the first returned datagram.
Datagram[]	getDatagrams(Unit unit, int reqSampleRate) Get the datagrams spanning a particular unit.
Datagram[]	getDatagrams(Unit unit, int reqSampleRate, long[] returnOffset) Get the datagrams spanning a particular unit, and return the time offset between the unit request and the actual location of the first returned datagram.
protected long	getDatagramsBytePos() Returns the position of the datagram zone in the original file.
TimelineReader.Index	getIndex() The index object.
protected Pair<ByteBuffer,Long>	getMappedByteBufferAtTime(long targetTimeInSamples)
protected Datagram	getNextDatagram(ByteBuffer bb) Read and return the upcoming datagram from the given byte buffer.
long	getNumDatagrams() Returns the number of datagrams in the timeline.
String	getProcHeaderContents() Return the content of the processing header as a String.
int	getSampleRate() Returns the timeline's sample rate.
long	getTotalDuration() Return the total duration of all data in this timeline.
protected long	hopToTime(ByteBuffer bb, long currentTimeInSamples, long targetTimeInSamples) Hop the datagrams in the given byte buffer until the one which begins at or contains the desired time (time is in samples; the sample rate is assumed to be that of the timeline).
protected void	load(String fileName) Load a timeline from a file.
protected void	load(String fileName, boolean tryMemoryMapping) Load a timeline from a file.
protected Pair<ByteBuffer,Long>	loadByteBufferAtTime(long targetTimeInSamples)
protected long	scaleTime(int reqSampleRate, long targetTimeInSamples) Scales a discrete time to the timeline's sample rate.
protected long	skipNextDatagram(ByteBuffer bb) Skip the upcoming datagram at the current position of the byte buffer.
protected long	unScaleTime(int reqSampleRate, long timelineTimeInSamples) Unscales a discrete time from the timeline's sample rate.

Methods inherited from class java.lang.Object

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

Field Detail

maryHdr

protected MaryHeader maryHdr

procHdr

protected TimelineReader.ProcHeader procHdr

idx

protected TimelineReader.Index idx

sampleRate

protected int sampleRate

numDatagrams

protected long numDatagrams

totalDuration

protected long totalDuration

The total duration of the timeline data, in samples. This is only computed upon request.

datagramsBytePos

protected int datagramsBytePos

timeIdxBytePos

protected int timeIdxBytePos

Constructor Detail

TimelineReader

public TimelineReader(String fileName)
               throws MaryConfigurationException

Construct a timeline from the given file name. Aiming for the fundamental guarantee: If an instance of this class is created, it is usable.

Parameters:

fileName - The file to read the timeline from. Must be non-null and point to a valid timeline file.

Throws:

NullPointerException - if null argument is given

MaryConfigurationException - if no timeline reader can be instantiated from fileName

TimelineReader

public TimelineReader(String fileName,
              boolean tryMemoryMapping)
               throws MaryConfigurationException

Construct a timeline from the given file name. Aiming for the fundamental guarantee: If an instance of this class is created, it is usable.

Parameters:

fileName - The file to read the timeline from. Must be non-null and point to a valid timeline file.

tryMemoryMapping - if true, will attempt to read audio data via a memory map, and fall back to piecewise reading. If false, will immediately go for piecewise reading using a RandomAccessFile.

Throws:

NullPointerException - if null argument is given

MaryConfigurationException - if no timeline reader can be instantiated from fileName

TimelineReader

protected TimelineReader()

Only subclasses can instantiate a TimelineReader object that doesn't call load(String). It is their responsibility then to ensure the fundamental guarantee.

Method Detail

load

protected void load(String fileName)
             throws IOException,
                    BufferUnderflowException,
                    MaryConfigurationException,
                    NullPointerException

Load a timeline from a file.

Parameters:

fileName - The file to read the timeline from. Must be non-null and point to a valid timeline file.

Throws:

IOException - if a problem occurs during reading

BufferUnderflowException - if a problem occurs during reading

MaryConfigurationException - if fileName does not point to a valid timeline file

NullPointerException

load

protected void load(String fileName,
        boolean tryMemoryMapping)
             throws IOException,
                    BufferUnderflowException,
                    MaryConfigurationException,
                    NullPointerException

Load a timeline from a file.

Parameters:

fileName - The file to read the timeline from. Must be non-null and point to a valid timeline file.

tryMemoryMapping - tryMemoryMapping

Throws:

IOException - if a problem occurs during reading

BufferUnderflowException - if a problem occurs during reading

MaryConfigurationException - if fileName does not point to a valid timeline file

NullPointerException - NullPointerException

getProcHeaderContents

public String getProcHeaderContents()

Return the content of the processing header as a String.

Returns:

a non-null string representing the proc header.

getNumDatagrams

public long getNumDatagrams()

Returns the number of datagrams in the timeline.

Returns:

the (non-negative) number of datagrams, as a long.

getDatagramsBytePos

protected long getDatagramsBytePos()

Returns the position of the datagram zone in the original file.

Returns:

the byte position of the datagram zone.

getSampleRate

public int getSampleRate()

Returns the timeline's sample rate.

Returns:

the sample rate as a positive integer.

getTotalDuration

public long getTotalDuration()
                      throws MaryConfigurationException

Return the total duration of all data in this timeline. Implementation note: this is an expensive operation that should not be used in production.

Returns:

a non-negative long representing the accumulated duration of all datagrams.

Throws:

MaryConfigurationException - if the duration cannot be obtained.

computeTotalDuration

protected void computeTotalDuration()
                             throws MaryConfigurationException

Compute the total duration of a timeline. This is an expensive method, since it goes through all datagrams to compute this duration. It should not normally be used in production.

Throws:

MaryConfigurationException - if the duration could not be computed.

getIndex

public TimelineReader.Index getIndex()

The index object.

Returns:

the non-null index object.

scaleTime

protected long scaleTime(int reqSampleRate,
             long targetTimeInSamples)

Scales a discrete time to the timeline's sample rate.

Parameters:

reqSampleRate - the externally given sample rate.

targetTimeInSamples - a discrete time, with respect to the externally given sample rate.

Returns:

a discrete time, in samples with respect to the timeline's sample rate.

unScaleTime

protected long unScaleTime(int reqSampleRate,
               long timelineTimeInSamples)

Unscales a discrete time from the timeline's sample rate.

Parameters:

reqSampleRate - the externally given sample rate.

timelineTimeInSamples - a discrete time, with respect to the timeline sample rate.

Returns:

a discrete time, in samples with respect to the externally given sample rate.

skipNextDatagram

protected long skipNextDatagram(ByteBuffer bb)
                         throws IOException

Skip the upcoming datagram at the current position of the byte buffer.

Parameters:

bb - bb

Returns:

the duration of the datagram we skipped

Throws:

IOException - if we cannot skip another datagram because we have reached the end of the byte buffer

getNextDatagram

protected Datagram getNextDatagram(ByteBuffer bb)

Read and return the upcoming datagram from the given byte buffer. Subclasses should override this method to create subclasses of Datagram.

Parameters:

bb - the timeline byte buffer to read from

Returns:

the current datagram, or null if EOF was encountered

hopToTime

protected long hopToTime(ByteBuffer bb,
             long currentTimeInSamples,
             long targetTimeInSamples)
                  throws IOException,
                         IllegalArgumentException

Hop the datagrams in the given byte buffer until the one which begins at or contains the desired time (time is in samples; the sample rate is assumed to be that of the timeline).

Parameters:

bb - the timeline byte buffer to use. Must not be null.

currentTimeInSamples - the time position corresponding to the current position of the byte buffer. Must not be negative.

targetTimeInSamples - the time location to reach. Must not be less than currentTimeInSamples

Returns:

the actual time at which we end up after hopping. This is less than or equal to targetTimeInSamples, never greater than it.

Throws:

IOException - if there is a problem skipping the datagrams

IllegalArgumentException - if targetTimeInSamples is less than currentTimeInSamples

getByteBufferAtTime

protected Pair<ByteBuffer,Long> getByteBufferAtTime(long targetTimeInSamples)
                                             throws IOException,
                                                    BufferUnderflowException

This method produces a new byte buffer whose current position represents the requested positionInFile. It cannot be assumed that a call to byteBuffer.position() produces any meaningful values. The byte buffer may represent only a part of the available data; however, at least one datagram can be read from the byte buffer. If no further data can be read from it, a new byte buffer must be obtained by calling this method again with a new target time.

Parameters:

targetTimeInSamples - the time position in the file which should be accessed as a byte buffer, in samples. Must be non-negative and less than the total duration of the timeline.

Returns:

a pair representing the byte buffer from which to read, and the exact time corresponding to the current position of the byte buffer. The position as such is not meaningful; the time is guaranteed to be less than or equal to targetTimeInSamples.

Throws:

IOException - IOException

BufferUnderflowException - , BufferUnderflowException if no byte buffer can be obtained for the requested time.

getMappedByteBufferAtTime

protected Pair<ByteBuffer,Long> getMappedByteBufferAtTime(long targetTimeInSamples)
                                                   throws IllegalArgumentException,
                                                          IOException

Throws:

IllegalArgumentException

IOException

loadByteBufferAtTime

protected Pair<ByteBuffer,Long> loadByteBufferAtTime(long targetTimeInSamples)
                                              throws IOException

Throws:

IOException

getDatagram

public Datagram getDatagram(long targetTimeInSamples)
                     throws IOException

Get a single datagram from a particular time location, given in the timeline's sampling rate.

Parameters:

targetTimeInSamples - the requested position, in samples. Must be non-negative and less than the total duration of the timeline.

Returns:

the datagram starting at or overlapping the given time, or null if end-of-file was encountered

Throws:

IOException - , BufferUnderflowException if no datagram could be created from the data at the given time.

getDatagram

public Datagram getDatagram(long targetTimeInSamples,
                   int reqSampleRate)
                     throws IOException

Get a single datagram from a particular time location.

Parameters:

targetTimeInSamples - the requested position, in samples. Must be non-negative and less than the total duration of the timeline.

reqSampleRate - the sample rate for the requested times.

Returns:

the datagram starting at or overlapping the given time, or null if end-of-file was encountered

Throws:

IOException - if no datagram could be created from the data at the given time.

getDatagrams

public Datagram[] getDatagrams(long targetTimeInSamples,
                      long timeSpanInSamples,
                      int reqSampleRate,
                      long[] returnOffset)
                        throws IOException

Get the datagrams spanning a particular time range from a particular time location, and return the time offset between the time request and the actual location of the first returned datagram. Irrespective of the value of timeSpanInSamples, at least one datagram is always returned.

Parameters:

targetTimeInSamples - the requested position, in samples. Must be non-negative and less than the total duration of the timeline.

timeSpanInSamples - the requested time span, in samples. If positive, then datagrams are selected by the given time span.

reqSampleRate - the sample rate for the requested and returned times. Must be positive.

returnOffset - an optional output field. If it is not null, then after the call it must have length of at least 1, and the first array field will contain the time difference, in samples, between the time request and the actual beginning of the first datagram.

Returns:

an array of datagrams containing at least one datagram. If less than the requested amount of datagrams can be read, the number of datagrams that can be read is returned.

Throws:

IllegalArgumentException - if targetTimeInSamples is negative, or if a returnOffset of length 0 is given.

IOException - , BufferUnderflowException if no data can be read at the given target time

getDatagrams

public Datagram[] getDatagrams(long targetTimeInSamples,
                      long timeSpanInSamples,
                      int reqSampleRate)
                        throws IOException

Get the datagrams spanning a particular time range from a particular time location. Irrespective of the value of timeSpanInSamples, at least one datagram is always returned.

Parameters:

targetTimeInSamples - the requested position, in samples. Must be non-negative and less than the total duration of the timeline.

timeSpanInSamples - the requested time span, in samples. If positive, then datagrams are selected by the given time span.

reqSampleRate - the sample rate for the requested and returned times. Must be positive.

Returns:

an array of datagrams containing at least one datagram. If less than the requested amount of datagrams can be read, the number of datagrams that can be read is returned.

Throws:

IllegalArgumentException - if targetTimeInSamples is negative, or if a returnOffset of length 0 is given.

IOException - if no data can be read at the given target time

getDatagrams

public Datagram[] getDatagrams(long targetTimeInSamples,
                      long timeSpanInSamples)
                        throws IOException

Get a given number of datagrams from a particular time location.

Parameters:

targetTimeInSamples - the requested position, in samples. Must be non-negative and less than the total duration of the timeline.

timeSpanInSamples - the span in samples

Returns:

an array of datagrams containing at least one datagram. If less than the requested amount of datagrams can be read, the number of datagrams that can be read is returned.

Throws:

IllegalArgumentException - if targetTimeInSamples is negative, or if a returnOffset of length 0 is given.

IOException - if no data can be read at the given target time

getDatagrams

public Datagram[] getDatagrams(long targetTimeInSamples,
                      int number,
                      int reqSampleRate,
                      long[] returnOffset)
                        throws IOException

Get a given number of datagrams from a particular time location, and return the time offset between the time request and the actual location of the first returned datagram.

Parameters:

targetTimeInSamples - the requested position, in samples. Must be non-negative and less than the total duration of the timeline.

number - the number of datagrams to read. Even if this is ≤ 0, at least one datagram is always returned.

reqSampleRate - the sample rate for the requested and returned times. Must be positive.

returnOffset - an optional output field. If it is not null, then after the call it must have length of at least 1, and the first array field will contain the time difference, in samples, between the time request and the actual beginning of the first datagram.

Returns:

an array of datagrams containing at least one datagram. If less than the requested amount of datagrams can be read, the number of datagrams that can be read is returned.

Throws:

IllegalArgumentException - if targetTimeInSamples is negative, or if a returnOffset of length 0 is given.

IOException - if no data can be read at the given target time

getDatagrams

public Datagram[] getDatagrams(Unit unit,
                      int reqSampleRate,
                      long[] returnOffset)
                        throws IOException

Get the datagrams spanning a particular unit, and return the time offset between the unit request and the actual location of the first returned datagram. Irrespective of the unit duration, at least one datagram is always returned.

Parameters:

unit - The requested speech unit, containing its own position and duration.

reqSampleRate - the sample rate for the requested and returned times. Must be positive.

returnOffset - an optional output field. If it is not null, then after the call it must have length of at least 1, and the first array field will contain the time difference, in samples, between the time request and the actual beginning of the first datagram.

Returns:

an array of datagrams containing at least one datagram. If less than the requested amount of datagrams can be read, the number of datagrams that can be read is returned.

Throws:

IllegalArgumentException - if targetTimeInSamples is negative, or if a returnOffset of length 0 is given.

IOException - if no data can be read at the given target time

getDatagrams

public Datagram[] getDatagrams(Unit unit,
                      int reqSampleRate)
                        throws IOException

Get the datagrams spanning a particular unit. Irrespective of the unit duration, at least one datagram is always returned.

Parameters:

unit - The requested speech unit, containing its own position and duration.

reqSampleRate - the sample rate for the requested and returned times. Must be positive.

Returns:

an array of datagrams containing at least one datagram. If less than the requested amount of datagrams can be read, the number of datagrams that can be read is returned.

Throws:

IllegalArgumentException - if targetTimeInSamples is negative, or if a returnOffset of length 0 is given.

IOException - if no data can be read at the given target time