-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Utility functions for processing MIDI files
--   
--   Common high-level tasks when processing MIDI files.
--   
--   <ul>
--   <li>Use tempos to translate between musical time (beats) and real time
--   (seconds).</li>
--   <li>Use time signatures to reference positions using measures instead
--   of just beats.</li>
--   <li>Find or change the names of MIDI tracks.</li>
--   </ul>
@package midi-util
@version 0.2


-- | It is recommended to view this Haddock documentation using the <tt>-q
--   local</tt> option so that, for example, the types
--   <tt>Data.EventList.Relative.TimeBody.T</tt>,
--   <tt>Sound.MIDI.File.T</tt>, and <tt>Sound.MIDI.File.Event.T</tt> don't
--   all get displayed simply as <tt>T</tt>. Otherwise, hover over the
--   types to see what is referred to.
module Sound.MIDI.Util

-- | Musical time, measured in beats a.k.a. quarter notes.
newtype Beats
Beats :: Rational -> Beats
[fromBeats] :: Beats -> Rational
data TimeSig
TimeSig :: !Beats -> !Beats -> TimeSig
[timeSigLength] :: TimeSig -> !Beats
[timeSigUnit] :: TimeSig -> !Beats

-- | Real time, measured in seconds.
newtype Seconds
Seconds :: Rational -> Seconds
[fromSeconds] :: Seconds -> Rational

-- | A ratio between musical time and real time, measured in beats per
--   second.
newtype BPS
BPS :: Rational -> BPS
[fromBPS] :: BPS -> Rational

-- | Assigns units to the tracks in a MIDI file. Supports both the common
--   ticks-based files as well as real-time SMPTE-encoded files.
decodeFile :: T -> Either [T Beats T] [T Seconds T]

-- | Encodes the tracks' beat positions in ticks, using the given
--   resolution. Positions will be rounded if necessary; see
--   <a>minResolution</a>.
encodeFileBeats :: Type -> Integer -> [T Beats T] -> T

-- | To correctly encode all the given tracks without rounding, the
--   resolution must be a multiple of the returned number.
minResolution :: [T Beats T] -> Integer

-- | Extracts the tempo from a tempo change event.
readTempo :: T -> Maybe BPS

-- | Creates a MIDI event to set the tempo to the given value. Rounds the
--   tempo to the nearest whole "microseconds per beat" if necessary.
showTempo :: BPS -> T

-- | Creates a tempo as a ratio of a music duration to a real time
--   duration.
makeTempo :: Beats -> Seconds -> BPS

-- | Uses a tempo to convert from musical time to real time.
applyTempo :: BPS -> Beats -> Seconds

-- | Uses a tempo to convert from real time to musical time.
unapplyTempo :: BPS -> Seconds -> Beats
applyTempoTrack :: TempoMap -> T Beats a -> T Seconds a
unapplyTempoTrack :: TempoMap -> T Seconds a -> T Beats a

-- | Converts between positions in musical time and real time.
data TempoMap
makeTempoMap :: T Beats T -> TempoMap
unmakeTempoMap :: TempoMap -> T Beats T
tempoMapFromBPS :: T Beats BPS -> TempoMap
tempoMapToBPS :: TempoMap -> T Beats BPS
applyTempoMap :: TempoMap -> Beats -> Seconds
unapplyTempoMap :: TempoMap -> Seconds -> Beats

-- | Given a MIDI event, if it is a time signature event, returns the
--   length of one measure set by the time signature.
readSignature :: T -> Maybe Beats
readSignatureFull :: T -> Maybe TimeSig

-- | Given a measure length, tries to encode it as a MIDI time signature.
showSignature :: Beats -> Maybe T
showSignatureFull :: TimeSig -> Maybe T

-- | Converts between a simple beat position, and a measure offset plus a
--   beat position.
data MeasureMap

-- | A number of measures (starting from 0), and an offset within that
--   measure (also starting from 0).
type MeasureBeats = (Int, Beats)

-- | What to do when <a>makeMeasureMap</a> finds a misaligned time
--   signature?
data MeasureMode

-- | Throw an exception.
Error :: MeasureMode

-- | Ignore it.
Ignore :: MeasureMode

-- | Truncate the previous measure.
Truncate :: MeasureMode

-- | The duration of a number of measures in a given time signature.
measures :: Int -> Beats -> Beats

-- | Computes the measure map, given the tempo track from the MIDI.
makeMeasureMap :: MeasureMode -> T Beats T -> MeasureMap
unmakeMeasureMap :: MeasureMap -> T Beats T
measureMapFromLengths :: MeasureMode -> T Beats Beats -> MeasureMap
measureMapToLengths :: MeasureMap -> T Beats Beats
measureMapFromTimeSigs :: MeasureMode -> T Beats TimeSig -> MeasureMap
measureMapToTimeSigs :: MeasureMap -> T Beats TimeSig

-- | Uses the measure map to compute which measure a beat position is in.
applyMeasureMap :: MeasureMap -> Beats -> MeasureBeats

-- | Uses the measure map to convert a measures+beats position to just
--   beats.
unapplyMeasureMap :: MeasureMap -> MeasureBeats -> Beats
measureLengthToTimeSig :: Beats -> TimeSig

-- | Looks for a track name event at position zero.
trackName :: (C t) => T t T -> Maybe String

-- | Removes any existing track name events at position zero and adds a new
--   one.
setTrackName :: (C t) => String -> T t T -> T t T
readTrackName :: T -> Maybe String
showTrackName :: String -> T

-- | Combines <a>trackTakeZero</a> and <a>trackDropZero</a>.
trackSplitZero :: (C t) => T t a -> ([a], T t a)

-- | Prepends the given events to the event list at position zero.
trackGlueZero :: (C t) => [a] -> T t a -> T t a

-- | Returns the list of events at position zero of the event list.
trackTakeZero :: (C t) => T t a -> [a]

-- | Drops all events at position zero of the event list.
trackDropZero :: (C t) => T t a -> (T t a)

-- | Equivalent to <a>join</a>, except <a>T</a> doesn't have a <a>Monad</a>
--   instance, presumably because <a>merge</a> has an <a>Ord</a>
--   constraint.
trackJoin :: (C t, Ord a) => T t (T t a) -> T t a

-- | Combines <a>trackTake</a> and <a>trackDrop</a>.
trackSplit :: (C t) => t -> T t a -> (T t a, T t a)

-- | Drops all events at or after the given time from the event list.
trackTake :: (C t) => t -> T t a -> T t a

-- | Drops the given amount of time from the start of the event list.
--   Events that are exactly at the time that is dropped will be kept in
--   the list.
trackDrop :: (C t) => t -> T t a -> T t a

-- | Finds and extracts the first event for which the function returns
--   <a>Just</a>.
extractFirst :: (C t) => (a -> Maybe b) -> T t a -> Maybe ((t, b), T t a)
instance GHC.Enum.Bounded Sound.MIDI.Util.MeasureMode
instance GHC.Enum.Enum Sound.MIDI.Util.MeasureMode
instance GHC.Read.Read Sound.MIDI.Util.MeasureMode
instance GHC.Show.Show Sound.MIDI.Util.MeasureMode
instance GHC.Classes.Ord Sound.MIDI.Util.MeasureMode
instance GHC.Classes.Eq Sound.MIDI.Util.MeasureMode
instance GHC.Classes.Eq Sound.MIDI.Util.MeasureMap
instance GHC.Classes.Eq Sound.MIDI.Util.TempoMap
instance GHC.Real.RealFrac Sound.MIDI.Util.BPS
instance GHC.Real.Fractional Sound.MIDI.Util.BPS
instance GHC.Real.Real Sound.MIDI.Util.BPS
instance GHC.Num.Num Sound.MIDI.Util.BPS
instance Numeric.NonNegative.Class.C Sound.MIDI.Util.BPS
instance GHC.Base.Monoid Sound.MIDI.Util.BPS
instance GHC.Show.Show Sound.MIDI.Util.BPS
instance GHC.Classes.Ord Sound.MIDI.Util.BPS
instance GHC.Classes.Eq Sound.MIDI.Util.BPS
instance GHC.Real.RealFrac Sound.MIDI.Util.Seconds
instance GHC.Real.Fractional Sound.MIDI.Util.Seconds
instance GHC.Real.Real Sound.MIDI.Util.Seconds
instance GHC.Num.Num Sound.MIDI.Util.Seconds
instance Numeric.NonNegative.Class.C Sound.MIDI.Util.Seconds
instance GHC.Base.Monoid Sound.MIDI.Util.Seconds
instance GHC.Show.Show Sound.MIDI.Util.Seconds
instance GHC.Classes.Ord Sound.MIDI.Util.Seconds
instance GHC.Classes.Eq Sound.MIDI.Util.Seconds
instance GHC.Show.Show Sound.MIDI.Util.TimeSig
instance GHC.Classes.Eq Sound.MIDI.Util.TimeSig
instance GHC.Real.RealFrac Sound.MIDI.Util.Beats
instance GHC.Real.Fractional Sound.MIDI.Util.Beats
instance GHC.Real.Real Sound.MIDI.Util.Beats
instance GHC.Num.Num Sound.MIDI.Util.Beats
instance Numeric.NonNegative.Class.C Sound.MIDI.Util.Beats
instance GHC.Base.Monoid Sound.MIDI.Util.Beats
instance GHC.Show.Show Sound.MIDI.Util.Beats
instance GHC.Classes.Ord Sound.MIDI.Util.Beats
instance GHC.Classes.Eq Sound.MIDI.Util.Beats
instance (GHC.Read.Read a, GHC.Read.Read b) => GHC.Read.Read (Sound.MIDI.Util.DoubleKey a b)
instance (GHC.Show.Show a, GHC.Show.Show b) => GHC.Show.Show (Sound.MIDI.Util.DoubleKey a b)
instance (GHC.Classes.Ord a, GHC.Classes.Ord b) => GHC.Classes.Eq (Sound.MIDI.Util.DoubleKey a b)
instance (GHC.Classes.Ord a, GHC.Classes.Ord b) => GHC.Classes.Ord (Sound.MIDI.Util.DoubleKey a b)
instance GHC.Show.Show Sound.MIDI.Util.TempoMap
instance GHC.Show.Show Sound.MIDI.Util.MeasureMap