audio_clock_bsd/
lib.rs

1//! Clock synchronization and timestamp conversion for real-time audio.
2//!
3//! This crate provides the [`ClockSource`] trait — the single contract a host
4//! application uses to map between an audio **sample index** and a wall-clock
5//! **PTP timestamp** (nanoseconds since the PTP epoch). It is the glue that
6//! lets an audio engine timestamp its samples for distributed playback
7//! (e.g. AES67/PTP-aligned streaming) or for offline alignment.
8//!
9//! ## Threading model
10//!
11//! A [`ClockSource`] is **not** a real-time-thread primitive: polling an NTP
12//! daemon or a PTP hardware clock, and running the drift-compensation loop, are
13//! blocking operations. A concrete clock is intended to live on a **separate
14//! thread** (or be polled periodically from a worker); the cheap, allocation-free
15//! [`ClockSource::sample_to_ptp`] / [`ClockSource::ptp_to_sample`] conversions
16//! may then be called from anywhere, including the RT audio thread.
17//!
18//! ## Backends
19//!
20//! - [`NtpClock`] — the default fallback, anchored to the system
21//!   monotonic/wall clock via [`std::time`]. Always available.
22//! - [`PtpClock`] — a `PTPv2` (IEEE 1588-2008) interface.
23//!   FreeBSD hardware PTP timestamping support is hardware-dependent, so the
24//!   concrete implementation reads PTP time from an injectable
25//!   [`PtpTimeProvider`] (e.g. a daemon-polling thread) and degrades to a
26//!   [`ClockError::Unavailable`] stub when none is present.
27//!
28//! ## Dependency licensing
29//!
30//! This crate depends on [`audio-core-bsd`] (**BSD-2-Clause**) and
31//! [`thiserror`] (**MIT OR Apache-2.0**). It links no system library, so it
32//! builds and tests anywhere.
33//!
34//! [`audio-core-bsd`]: https://crates.io/crates/audio-core-bsd
35//! [`thiserror`]: https://crates.io/crates/thiserror
36
37#![cfg_attr(docsrs, feature(doc_cfg))]
38#![warn(missing_docs)]
39#![warn(clippy::all, clippy::pedantic)]
40
41pub mod clock;
42pub mod error;
43pub mod ntp;
44pub mod ptp;
45
46pub use clock::{ClockAnchor, ClockSource};
47pub use error::{ClockError, Result};
48pub use ntp::NtpClock;
49pub use ptp::{PtpClock, PtpTimeProvider};
audio_clock_bsd/lib.rs

audio_clock_bsd/
lib.rs
