Comment by mojuba
6 years ago
In some areas Apple's documentation is dismal to the point of being ridiculously useless. Like this (from CoreAudio):
mWordClockTime
The word clock time.
And nothing else on that page apart from that it's UInt64. And it's been like this for years if not decades already. Nothing's changed since the APIs were also bridged and the documentation re-written for Swift. I doubt it's the intent (to keep the developers in the dark with regard to CoreAudio? unlikely), just neglect. Apple, otherwise one of the few companies that pays attention to details and have unlimited resources for this type of tasks, what's their problem really?
In fairness, "word clock" is a term of art in professional digital audio: this is literally just a sample count so it is unit-less.
>And nothing else on that page apart from that it's UInt64.
What else exactly do you need?
It's a reference page for the members of the struct AudioTimeSTamp:
https://developer.apple.com/documentation/coreaudiotypes/aud...
I wish many C/C++ libs had such a good documentation...
> What else exactly do you need?
What unit it reflects. What epoch it uses. When does it wraparound? Is it realtime? Or best guess? Is it wall-clock like CLOCK_REALTIME or is closer to CLOCK_MONOTONIC? Is a valid range the entirety of possible uint64 values, or is there a range limit?
The answer is “not applicable” to all of these. The word clock is unit less, just ticking up each sample. It’s not actually a clock in the normal sense, there is no leap years or anything in it. It’s used to synchronize devices.
Granted, the documentation isn’t the best at explaining it. But if you know what a word clock is in terms of audio, you know what the value is; a counter.
7 replies →
> What else exactly do you need?
I always like to know the units (seconds? nanoseconds?) and the reference-year (1970? 2001? 1601?)
Also, how are leap seconds reflect in this value if at all?
Apple should look at linux's manpage on the `time` syscall for inspiration.
That’s much better than some of the other “documentation” that Apple has…