HarmTrace.Base.Time

Summary: A set of types and classes for representing musical time, mainly (but not necessarily) in the context of recognising chords from an arbitrary audio source.

Documentation

type NumData = Double

A type synonym is defined for our main numerical representation, this allows us to easily change the precision.

Representing musical time

data Timed a

A datatype that wraps around an (musical) datatype, adding information about the musical time to this datatype. Musical time is stored as a list of BeatTime time stamps that can optionally be augmented with information about the Beat position of the particular time stamp inside the bar.

Constructors

Timed

Fields

getData :: a

Returns the contained datatype

getTimeStamps :: [BeatTime]

Returns the list of TimeStamps

Instances

Functor Timed

Eq a => Eq (Timed a)

Show a => Show (Timed a)

data Beat

For now, we fix the number of available beats to four, because this is also hard-coded into the bar and beat-tracker.

Constructors

One

Two

Three

Four

NoBeat

Instances

Enum Beat

Eq Beat

Ord Beat

Show Beat

data BeatTime

Represents a musical time stamp, which is a NumData possibly augmented with a Beat denoting the position of the time stamp within a bar.

Constructors

BeatTime NumData Beat

Time NumData

Instances

Eq BeatTime

Ord BeatTime

Show BeatTime

Functions

Data access

timed :: a -> NumData -> NumData -> Timed a

alternative Timed constructor

timedBT :: a -> BeatTime -> BeatTime -> Timed a

alternative Timed constructor

getBeatTime :: Timed a -> BeatTime

Returns the start time stamp

getBeat :: Timed a -> Beat

Returns the start Beat

onset :: Timed a -> NumData

Returns the onset time stamp

offset :: Timed a -> NumData

Returns the offset time stamp

duration :: Timed a -> NumData

Returns the duration of Timed

setData :: Timed a -> b -> Timed b

wraps a datatype in Timed

getEndTime :: [Timed a] -> NumData

Given a list of Timed values, returns the end time of the latest element in the list.

Type conversion and other utilities

mergeTimed :: Eq a => [Timed a] -> [Timed a]

merges consecutive Timed values that store the same element (using ('(==)'). For example:

>>> mergeTimed [timed "c" 0 1, timed "c" 1 2, timed "d" 3 4, timed "d" 4 5, timed "e" 5 6]
>>> [Timed {getData = "c", getTimeStamps = [(0.0),(1.0),(2.0)]}
>>> ,Timed {getData = "d", getTimeStamps = [(3.0),(4.0),(5.0)]}
>>> ,Timed {getData = "e", getTimeStamps = [(5.0),(6.0)]}]

mergeTimedWith :: forall a. Eq a => (a -> a -> Bool) -> [Timed a] -> [Timed a]

Does exactly what mergeTimed does, but allows for a custom equality function

expandTimed :: [Timed a] -> [Timed a]

the inverse of mergeTimed, expanding the list Timed elements to all timestamps stored in the getTimeStamps list. N.B.

>>> expandTimed (mergeTimed x) = x :: [Timed a]

also,

>>> (expandTimed cs) = cs

and,

>>> mergeTimed (mergeTimed (mergeTimed cs)) = (mergeTimed cs)

hold. This has been tested on the first tranche of 649 Billboard songs.

concatTimed :: a -> Timed a -> Timed a -> Timed a

concatenates the BeatTime timestamps of two Timeds and creates a new Timed that stores the first argument. N.B. this function uses timeComp to allow for very small timing deviations

splitTimed :: Show a => Timed a -> NumData -> (Timed a, Timed a)

Splits a Timed in two Timeds at the specified position. If the position is out of range, an error is thrown.

>>> splitTimed (Timed "x" [Time 2, Time 5]) 4
>>> ( Timed {getData = "x", getTimeStamps = [(2.0),(4.0)]}
>>> , Timed {getData = "x", getTimeStamps = [(4.0),(5.0)]} )

nextBeat :: Beat -> Beat

returns the next beat, e.g. nextBeat Two = Three . Following the (current) definition of Beat, we still assume 4/4, in the future this function should also have the meter as an argument.

prevBeat :: Beat -> Beat

returns the previous Beat, similar to prevBeat.

returns the next beat, e.g. nextBeat Two = Three . Following the (current) definition of Beat, we still assume 4/4, in the future this function should also have the meter as an argument.

dropTimed :: [Timed a] -> [a]

drops the time (with or without Beat) information of a list Timed data structure

timeStamp :: BeatTime -> NumData

Returns the NumData timestamp, given a BeatTime

timeComp :: NumData -> NumData -> Ordering

compares to NumData timestamps taking a rounding error roundingError into account.

roundingError :: NumData

When reducing and expanding Timed types there might be rounding errors in the floating point time stamps. The roundingError parameter sets the acceptable rounding error that is used in the comparison of time stamps (e.g. see timeComp)

beat :: BeatTime -> Beat

Returns the NumData timestamp, given a BeatTime

pprint :: Show a => Timed a -> String

Pretty prints a single Timed

prettyPrint :: Show a => [Timed a] -> String

Pretty prints a list of Timeds, one per line