Temporal.Media

A library for creating lists of constant time events related in time.

Introduction

Temporal.Media is a library for creating lists of constant time events related in time. Constant time event is value that starts at some fixed time and lasts for some fixed time. Library provides functions to build lists of such events with time-relations like sequent, parallel or delayed.

Core type of library is Track. It provides interface to compose list of events.

Types

data Event t a

Constant time events. Value a starts at some time and lasts for some time.

Constructors

Event

Fields

eventStart :: t

eventDur :: t

eventContent :: a

Instances

Functor (Event t)

(Eq t, Eq a) => Eq (Event t a)

(Show t, Show a) => Show (Event t a)

data Track t a

Track is a set of Event s. There is total duration of the track, but Events can go beyond the scope of total duration (as a result of mapEvents function). Total duration is used in sequent composition of tracks.

Instances

Functor (Track t)

Foldable (Track t)

Traversable (Track t)

(Eq t, Eq a) => Eq (Track t a)

(Show t, Show a) => Show (Track t a)

Real t => Monoid (Track t a)

dur :: Track t a -> t

Calculates track's duration.

within :: Real t => t -> t -> Event t a -> Bool

Tests if given Event happens between two time stamps.

eventEnd :: Num t => Event t a -> t

End point of event (start time plus duration).

Composition

temp :: Real t => a -> Track t a

temp constructs just an event. Value of type a lasts for one time unit and starts at zero.

event :: Real t => t -> a -> Track t a

Creates a single event.

 event dur a 

Event lasts for some time and contains a value a.

stretch :: Real t => t -> Track t a -> Track t a

Stretches track in time domain.

delay :: Real t => t -> Track t a -> Track t a

Delays all events by given duration.

reflect :: Real t => Track t a -> Track t a

Reversing the tracks

(+|) :: Real t => t -> Track t a -> Track t a

Infix delay function.

(*|) :: Real t => t -> Track t a -> Track t a

Infix stretch function.

(=:=) :: Real t => Track t a -> Track t a -> Track t a

Parallel composition. Play two tracks simultaneously.

(+:+) :: Real t => Track t a -> Track t a -> Track t a

Sequent composition. Play first track then second.

(=:/) :: Real t => Track t a -> Track t a -> Track t a

Turncating parallel composition. Total duration equals to minimum of the two tracks. All events that goes beyond the lmimt are dropped.

line :: Real t => [Track t a] -> Track t a

Sequent composition on list of tracks.

chord :: (Real t, Ord t) => [Track t a] -> Track t a

Parallel composition on list of tracks.

chordT :: Real t => [Track t a] -> Track t a

Turncating parallel composition on list of tracks.

loop :: Real t => Int -> Track t a -> Track t a

Analog of replicate function for tracks. Replicated tracks are played sequentially.

rest :: Real t => t -> Track t a

Empty track that lasts for some time.

sustain :: Real t => t -> Track t a -> Track t a

After this transformation events last longer by some constant amount of time.

sustainT :: Real t => t -> Track t a -> Track t a

Prolongated events can not exceed total track duration. All event are sustained but those that are close to end of the track are sliceped. It resembles sustain on piano, when track ends you release the pedal.

Common patterns

lineTemp :: Real t => [a] -> Track t a

A line of one events. Each of them lasts for one second.

chordTemp :: Real t => [a] -> Track t a

A chord of one events. Each of them lasts for one second.

lineMap :: Real t => (a -> Track t b) -> [a] -> Track t b

Transforms a sequence and then applies a line.

chordMap :: Real t => (a -> Track t b) -> [a] -> Track t b

Transforms a sequence and then applies a chord.

chordTMap :: Real t => (a -> Track t b) -> [a] -> Track t b

Transforms a sequence and then applies a chordT.

Filtering

slice :: Real t => t -> t -> Track t a -> Track t a

slice cuts piece of value within given time interval. for (slice t0 t1 m), if t1 < t0 result is reversed. If t0 is negative or t1 goes beyond dur m blocks of nothing inserted so that duration of result equals to abs (t0 - t1).

takeT :: Real t => t -> Track t a -> Track t a

(takeT t) is equivalent to (slice 0 t).

dropT :: Real t => t -> Track t a -> Track t a

(dropT t m) is equivalent to (slice t (dur a) a).

filterEvents :: Real t => (Event t a -> Bool) -> Track t a -> Track t a

Filter track.

Mappings

mapEvents :: Real t => (Event t a -> Event t b) -> Track t a -> Track t b

General mapping. Mapps not only values but events.

tmap :: Real t => (Event t a -> b) -> Track t a -> Track t b

Mapps values and time stamps.

tmapRel :: RealFrac t => (Event t a -> b) -> Track t a -> Track t b

Relative tmap. Time values are normalized by argument's duration.

Rendering

render :: Real t => Track t a -> [Event t a]

Get all events on recordered on the track.

alignByZero :: Real t => [Event t a] -> [Event t a]

Shifts all events so that minimal start time equals to zero if first event has negative start time.

sortEvents :: Ord t => [Event t a] -> [Event t a]

Sorts all events by start time.

Monoid synonyms

This package heavily relies on Monoids, so there are shorcuts for Monoid methods.

nil :: Monoid a => a

Synonym for method mempty.

module Data.Monoid

Miscellaneous

linfun :: (Ord t, Fractional t) => [t] -> t -> t

Linear interpolation. Can be useful with mapEvents for envelope changes.

 linfun [a, da, b, db, c, ... ]

a, b, c ... - values

da, db, ... - duration of segments

linfunRel :: (Ord t, Fractional t) => t -> [t] -> t -> t

With linfunRel you can make linear interpolation function that has equal distance between points. First argument gives total length of the interpolation function and second argument gives list of values. So call

 linfunRel dur [a1, a2, a3, ..., aN]

is equivalent to:

 linfun [a1, dur/N, a2, dur/N, a3, ..., dur/N, aN]