Sound.OSC.Time

OSC related timing functions. OSC timestamps are 64-bit NTP values, http://ntp.org/.

Temporal types

type NTP64 = Word64

Type for binary (integeral) representation of a 64-bit NTP timestamp (ie. ntpi). The NTP epoch is January 1, 1900. NTPv4 also includes a 128-bit format, which is not used by OSC.

type Time = Double

NTP time in real-valued (fractional) form (ie. ntpr). This is the primary form of timestamp used by hosc.

immediately :: Time

Constant indicating a bundle to be executed immediately. It has the NTP64 representation of 1.

type UT = Double

Unix/Posix time in real-valued (fractional) form. The Unix/Posix epoch is January 1, 1970.

Time conversion

ntpr_to_ntpi :: Time -> NTP64

Convert a real-valued NTP timestamp to an NTPi timestamp.

ntpr_to_ntpi immediately == 1
fmap ntpr_to_ntpi time

ntpi_to_ntpr :: NTP64 -> Time

Convert an NTPi timestamp to a real-valued NTP timestamp.

ntp_ut_epoch_diff :: Num n => n

Difference (in seconds) between NTP and UT epochs.

ntp_ut_epoch_diff / (24 * 60 * 60) == 25567
25567 `div` 365 == 70

ut_to_ntpi :: UT -> NTP64

Convert a UT timestamp to an NTPi timestamp.

ut_to_ntpr :: Num n => n -> n

Convert Unix/Posix to NTP.

ntpr_to_ut :: Num n => n -> n

Convert NTP to Unix/Posix.

ntpi_to_ut :: NTP64 -> UT

Convert NTPi to Unix/Posix.

ntpr_to_posixtime :: Time -> POSIXTime

Convert Time to POSIXTime.

posixtime_to_ntpr :: POSIXTime -> Time

Convert POSIXTime to Time.

Time inter-operation.

ut_epoch :: UTCTime

The time at 1970-01-01:00:00:00.

utc_to_ut :: Fractional n => UTCTime -> n

Convert UTCTime to Unix/Posix.

Clock operations

time :: MonadIO m => m Time

Read current real-valued NTP timestamp.

get_ct = fmap utc_to_ut T.getCurrentTime
get_pt = fmap realToFrac T.getPOSIXTime
(ct,pt) <- get_ct >>= \t0 -> get_pt >>= \t1 -> return (t0,t1)
print (pt - ct,pt - ct < 1e-5)

Thread operations.

pauseThreadLimit :: Fractional n => n

The pauseThread limit (in seconds). Values larger than this require a different thread delay mechanism, see sleepThread. The value is the number of microseconds in maxBound::Int.

pauseThread :: (MonadIO m, RealFrac n) => n -> m ()

Pause current thread for the indicated duration (in seconds), see pauseThreadLimit.

wait :: MonadIO m => Double -> m ()

Type restricted pauseThread.

pauseThreadUntil :: MonadIO m => Time -> m ()

Pause current thread until the given Time, see pauseThreadLimit.

sleepThread :: (RealFrac n, MonadIO m) => n -> m ()

Sleep current thread for the indicated duration (in seconds). Divides long sleeps into parts smaller than pauseThreadLimit.

sleepThreadUntil :: MonadIO m => Time -> m ()

Sleep current thread until the given Time. Divides long sleeps into parts smaller than pauseThreadLimit.

Pretty printing

iso_8601_fmt :: String

Detailed 37-character ISO 8601 format, including fractional seconds and '+0000' suffix.

iso_8601_to_utctime :: String -> Maybe UTCTime

Parse time according to iso_8601_fmt

iso_8601_to_utctime "2015-11-26T00:29:37,145875000000+0000"

utctime_to_iso_8601 :: UTCTime -> String

UTC time in iso_8601_fmt.

tm <- fmap (utctime_to_iso_8601 . T.posixSecondsToUTCTime) T.getPOSIXTime
(length tm,sum [4+1+2+1+2,1,2+1+2+1+2,1,12,1,4],sum [10,1,8,1,12,1,4]) == (37,37,37)

ntpr_to_iso_8601 :: Time -> String

ISO 8601 of Time.

tm <- fmap ntpr_to_iso_8601 time
import System.Process {- process -}
rawSystem "date" ["-d",tm]

t = 15708783354150518784
s = "2015-11-26T00:22:19,366058349609+0000"
ntpr_to_iso_8601 (ntpi_to_ntpr t) == s

iso_8601_to_ntpr :: String -> Maybe Time

Time of ISO 8601.

t = 15708783354150518784
s = "2015-11-26T00:22:19,366058349609+0000"
fmap ntpr_to_ntpi (iso_8601_to_ntpr s) == Just t

time_pp :: Time -> String

Alias for ntpr_to_iso_8601.

time_pp immediately == "1900-01-01T00:00:00,000000000000+0000"
fmap time_pp time