diff --git a/c/moq/test/probe.c b/c/moq/test/probe.c index 045f6a960ac..e21c6057064 100644 --- a/c/moq/test/probe.c +++ b/c/moq/test/probe.c @@ -370,16 +370,16 @@ int main(void) moq_frame frame = moq_frame_default(); frame.payload.data = hello; frame.payload.len = sizeof(hello); - frame.timestamp_us.has_value = true; - frame.timestamp_us.value = 1000; + moq_timestamp timestamp = {1000, 1000000}; + frame.timestamp = ×tamp; ok(moq_track_producer_write_frame(track, &frame), "write_frame"); moq_frame *received = await(&reading, "read_frame"); moq_task_free(task); CHECK(received); CHECK(received->payload.len == sizeof(hello)); CHECK(memcmp(received->payload.data, hello, sizeof(hello)) == 0); - /* Lite-07 carries both the Implementation parameter and frame timestamps. */ - CHECK(received->timestamp_us.has_value && received->timestamp_us.value == 1000); + /* Lite-07 carries both the Implementation parameter and frame timestamps, at any scale. */ + CHECK(received->timestamp && received->timestamp->value * 1000000 == 1000 * received->timestamp->scale); moq_frame_free(received); CHECK(!cancelled.done); diff --git a/cpp/moq/bench/main.cpp b/cpp/moq/bench/main.cpp index c5accddfc2e..91653e4326c 100644 --- a/cpp/moq/bench/main.cpp +++ b/cpp/moq/bench/main.cpp @@ -90,7 +90,8 @@ Reader read(Case c, std::shared_ptr consumer, const std::vec require(group != nullptr); for (int f = 0; f < c.frames(); ++f) { auto frame = ok(co_await group->read_frame()); - require(frame && frame->payload == payload && frame->timestamp_us == n * c.frames() + f); + require(frame && frame->payload == payload && frame->timestamp && + frame->timestamp->value == n * c.frames() + f); } } @@ -119,7 +120,7 @@ void throughput(Case c, double budget, std::vector &results) for (auto &track : tracks) { auto group = ok(track->append_group()); for (int f = 0; f < c.frames(); ++f) - ok(group->write_frame({payload, n * c.frames() + f})); + ok(group->write_frame({payload, moq::Timestamp{n * c.frames() + f, 1000000}})); ok(group->finish()); } for (auto &reader : readers) { diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index 15f1c95510f..23e4aaacff3 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -105,6 +105,43 @@ Coroutine read_one(std::shared_ptr consumer, std::optionalpublish_track("timed", timed), "publish timed track"); + auto consumer = ok(track->consume(std::nullopt), "consume timed track"); + for (uint64_t value : {0, 1}) { + ok(track->write_frame({bytes("tick"), moq::Timestamp{value, 90000}}), "write tick"); + auto frame = ok(consumer->read_frame().get(), "read tick"); + CHECK(frame && frame->timestamp); + CHECK(frame->timestamp->value == value && frame->timestamp->scale == 90000); + } + for (const moq::Timestamp &invalid : + {moq::Timestamp{0, 0}, moq::Timestamp{0, uint64_t(1) << 62}, moq::Timestamp{uint64_t(1) << 61, 90000}}) { + auto refused = track->write_frame({bytes("tick"), invalid}); + CHECK(!refused); + CHECK(std::holds_alternative(refused.error().get_variant())); + } + + auto untimed = ok(broadcast->publish_track("untimed", std::nullopt), "publish untimed track"); + auto untimed_consumer = ok(untimed->consume(std::nullopt), "consume untimed track"); + ok(untimed->write_frame({bytes("untimed"), std::nullopt}), "write untimed"); + auto frame = ok(untimed_consumer->read_frame().get(), "read untimed"); + CHECK(frame && !frame->timestamp); + ok(broadcast->close(), "close timestamp broadcast"); +} + // Only the defaults carry moq-net's zero max delay; a bare record sets no subscriber limit. void subscription_defaults() { @@ -144,7 +181,7 @@ void audio_roundtrip() sizeof(value)); } } - ok(audio->write({250000 + packet * 20000, data}), "write audio"); + ok(audio->write({{250000 + packet * 20000, 1000000}, data}), "write audio"); } ok(audio->finish(), "finish audio"); size_t frames = 0; @@ -156,7 +193,7 @@ void audio_roundtrip() CHECK(!std::holds_alternative(read->get_variant())); // The finish ends the encoder where its eight 20 ms frames stop. if (const auto *end = std::get_if(&read->get_variant())) { - CHECK(end->end_us == 250000 + 8 * 20000); + CHECK(same_time(end->end, {250000 + 8 * 20000, 1000000})); continue; } const auto *variant = std::get_if(&read->get_variant()); @@ -164,7 +201,7 @@ void audio_roundtrip() const auto *next = &variant->frame; - CHECK(next->timestamp_us == 250000 + frames * 1000000 / 48000); + CHECK(same_time(next->timestamp, {250 * 48000 + frames * 1000, 48000000})); CHECK(next->data.size() % (2 * sizeof(float)) == 0); for (size_t sample = 0; sample < next->data.size() / (2 * sizeof(float)); sample++) { for (size_t channel = 0; channel < 2; channel++) { @@ -188,7 +225,7 @@ void audio_roundtrip() }; CHECK(power(channel) > power(1 - channel)); } - CHECK(!audio->write({0, std::vector(8)})); + CHECK(!audio->write({{0, 1000000}, std::vector(8)})); ok(broadcast->close(), "close audio broadcast"); } @@ -196,6 +233,7 @@ void audio_roundtrip() int main() { + timestamp_roundtrip(); subscription_defaults(); audio_roundtrip(); auto timebase_owner = ok(moq::BroadcastProducer::init(), "timebase owner"); @@ -296,14 +334,14 @@ int main() // The consumer survives the cancelled read and delivers the next frame. auto reading = consumer->read_frame(); - ok(track->write_frame({bytes("hello"), 1000}), "write_frame"); + ok(track->write_frame({bytes("hello"), moq::Timestamp{1000, 1000000}}), "write_frame"); auto frame = ok(reading.get(), "read_frame"); // get() consumed the state. CHECK(!reading.valid()); CHECK(frame.has_value()); CHECK(frame->payload == bytes("hello")); // Lite-07 carries both the Implementation parameter and frame timestamps. - CHECK(frame->timestamp_us == 1000); + CHECK(frame->timestamp && same_time(*frame->timestamp, {1000, 1000000})); // A continuation receives the next frame on the executor. { @@ -318,7 +356,7 @@ int main() }); // then() took the future's state. CHECK(!reading_next.valid()); - ok(track->write_frame({bytes("then"), 2000}), "write_frame"); + ok(track->write_frame({bytes("then"), moq::Timestamp{2000, 1000000}}), "write_frame"); CHECK(done.wait_for(5s)); CHECK(received && received->payload == bytes("then")); } @@ -338,7 +376,7 @@ int main() Latch done; std::optional received; auto reader = read_one(consumer, received, done); - ok(track->write_frame({bytes("co_await"), 3000}), "write_frame"); + ok(track->write_frame({bytes("co_await"), moq::Timestamp{3000, 1000000}}), "write_frame"); CHECK(done.wait_for(5s)); CHECK(received && received->payload == bytes("co_await")); (void)reader; diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 2243dff672e..b6791870781 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -7,7 +7,6 @@ #include "moq-settings.h" #include "moq-url.h" #include "logger.h" -#include "util/util_uint64.h" #include #include @@ -605,20 +604,20 @@ void MoQOutput::Data(struct encoder_packet *packet) } // The packet's timestamp on the broadcast clock, or nothing when it falls before zero. -static std::optional PacketTimestamp(const struct encoder_packet *packet) +static std::optional PacketTimestamp(const struct encoder_packet *packet) { - // Add ~1 second offset to handle negative PTS from audio priming frames, and - // the same to video for A/V sync. - // TODO: This is slightly wrong when den is not evenly divisible by num, but close enough. - int64_t pts = packet->pts + packet->timebase_den / packet->timebase_num; - if (pts < 0) + // A tick is num/den seconds, so den units per second hold it exactly, 1001/30000 included. + // Offset by one second to cover the negative PTS of audio priming frames, and video by + // the same for A/V sync. + const int64_t value = packet->pts * packet->timebase_num + packet->timebase_den; + if (value < 0) return std::nullopt; - return util_mul_div64(pts, 1000000ULL * packet->timebase_num, packet->timebase_den); + return moq::Timestamp{static_cast(value), static_cast(packet->timebase_den)}; } -static moq::Frame PacketFrame(const struct encoder_packet *packet, uint64_t timestamp_us) +static moq::Frame PacketFrame(const struct encoder_packet *packet, const moq::Timestamp ×tamp) { - return moq::Frame{std::vector(packet->data, packet->data + packet->size), timestamp_us}; + return moq::Frame{std::vector(packet->data, packet->data + packet->size), timestamp}; } void MoQOutput::AudioData(struct encoder_packet *packet) diff --git a/cpp/obs/src/moq-source.cpp b/cpp/obs/src/moq-source.cpp index 1569b9874fc..fad23a832b9 100644 --- a/cpp/obs/src/moq-source.cpp +++ b/cpp/obs/src/moq-source.cpp @@ -4,6 +4,7 @@ #include #include #include +#include #include @@ -76,6 +77,13 @@ namespace { struct moq_source; +// A track timestamp in the nanoseconds OBS stamps media with, floored when the scale does not +// divide a second evenly into nanoseconds. +static uint64_t moq_source_nanoseconds(const moq::Timestamp ×tamp) +{ + return util_mul_div64(timestamp.value, 1'000'000'000, timestamp.scale); +} + enum class Decoded { Pending, Ready, Failed }; // Full: the decoder refused the packet until its pending pictures are taken. enum class Sent { Accepted, Full, Failed }; @@ -87,7 +95,7 @@ struct VideoDecoder { SwsContext *sws_ctx = nullptr; bool got_keyframe = false; // End can precede the old encoder's final packets, whose timestamps are below it. - std::optional end_us; + std::optional end_ns; uint32_t frames_waiting_for_keyframe = 0; uint32_t consecutive_decode_errors = 0; obs_source_frame frame = {}; @@ -728,18 +736,18 @@ static void moq_source_on_frame(struct moq_source *ctx, const std::shared_ptrvideo_decoder; const auto &variant = (*result)->get_variant(); if (const auto *end = std::get_if(&variant)) { - decoder.end_us = end->end_us; + decoder.end_ns = moq_source_nanoseconds(end->end); moq_source_read_track(ctx, conn, track); return; } const auto *read = std::get_if(&variant); - if (!read || (decoder.end_us && read->frame.timestamp_us >= *decoder.end_us)) { + if (!read || (decoder.end_ns && moq_source_nanoseconds(read->frame.timestamp) >= *decoder.end_ns)) { // A gap loses references immediately. An end does so only at the fresh encoder, // after all old tail packets below its endpoint have entered the decoder. moq_source_drain_video(ctx, conn, track); avcodec_flush_buffers(decoder.codec_ctx); decoder.got_keyframe = false; - decoder.end_us.reset(); + decoder.end_ns.reset(); } if (!read) { moq_source_read_track(ctx, conn, track); @@ -814,7 +822,7 @@ static bool moq_source_on_audio_read(struct moq_source *ctx, const std::shared_p audio.format = AUDIO_FORMAT_FLOAT_PLANAR; audio.samples_per_sec = layout.sample_rate; // The same broadcast timeline video stamps, in the nanoseconds OBS expects. - audio.timestamp = frame.timestamp_us * 1000; + audio.timestamp = moq_source_nanoseconds(frame.timestamp); if (track == conn->pending_audio) conn->audio = std::move(conn->pending_audio); @@ -1146,9 +1154,9 @@ static std::unique_ptr moq_source_prepare_decoder(const moq::Video } } - // Packets carry the frame's microsecond timestamp, which the decoder hands back on the - // picture it belongs to. - decoder->codec_ctx->pkt_timebase = AVRational{1, 1'000'000}; + // Packets carry the frame's timestamp in OBS's nanoseconds, which the decoder hands back + // on the picture it belongs to. + decoder->codec_ctx->pkt_timebase = AVRational{1, 1'000'000'000}; // Open codec if (avcodec_open2(decoder->codec_ctx, codec, NULL) < 0) { @@ -1200,7 +1208,7 @@ static Sent moq_source_send_packet(VideoDecoder &decoder, const moq::MediaFrame packet->size = static_cast(frame_data.payload.size()); // The decoder hands this back on the picture it belongs to. Decode order has no // timestamp of its own here, so dts stays unset. - packet->pts = static_cast(frame_data.timestamp_us); + packet->pts = static_cast(moq_source_nanoseconds(frame_data.timestamp)); // Send packet to decoder int ret = avcodec_send_packet(decoder.codec_ctx, packet); @@ -1366,8 +1374,8 @@ static Decoded moq_source_receive_frame(VideoDecoder &decoder) return Decoded::Failed; } - // OBS expects nanoseconds; packets carry microseconds. - decoder.frame.timestamp = static_cast(frame->best_effort_timestamp) * 1000; + // Packets already carry the nanoseconds OBS expects. + decoder.frame.timestamp = static_cast(frame->best_effort_timestamp); decoder.frame.format = VIDEO_FORMAT_RGBA; av_frame_free(&frame); return Decoded::Ready; diff --git a/cpp/obs/test/moq-audio-encoder-test.cpp b/cpp/obs/test/moq-audio-encoder-test.cpp index 6c1f969702f..d8f3dc6c5dc 100644 --- a/cpp/obs/test/moq-audio-encoder-test.cpp +++ b/cpp/obs/test/moq-audio-encoder-test.cpp @@ -183,11 +183,11 @@ std::vector NoiseFrame(uint32_t &state, size_t samples) return pcm; } -// MoQOutput's conversion of an OBS packet's timestamp to the track's microseconds. -uint64_t PacketMicros(const encoder_packet &packet) +// MoQOutput's conversion of an OBS packet's timestamp to the track's. +moq::Timestamp PacketTimestamp(const encoder_packet &packet) { - const int64_t pts = packet.pts + packet.timebase_den / packet.timebase_num; - return static_cast(pts) * 1000000ULL * packet.timebase_num / packet.timebase_den; + const int64_t value = packet.pts * packet.timebase_num + packet.timebase_den; + return moq::Timestamp{static_cast(value), static_cast(packet.timebase_den)}; } // Publishes `count` tone packets from an encoder with `settings` the way MoQOutput @@ -242,8 +242,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) const int count = 50; const int64_t start = 3 * RATE; // Where input sample `index` lands on the track: MoQOutput's one second offset on top. - auto micros = [&](int64_t index) { - return static_cast((start + RATE + index) * 1000000LL / RATE); + auto sample = [&](int64_t index) { + return static_cast(start + RATE + index); }; for (int i = 0; i < count; i++) { const int64_t pts = start + i * static_cast(encoder.frame_size); @@ -253,8 +253,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) if (!packet) return; CHECK(packet->pts == pts && packet->dts == pts); - const uint64_t us = PacketMicros(*packet); - TestOk(track->write_frame({std::vector(packet->data, packet->data + packet->size), us}), + TestOk(track->write_frame({std::vector(packet->data, packet->data + packet->size), + PacketTimestamp(*packet)}), "write_frame"); TestOk(track->cut(), "cut"); } @@ -265,7 +265,7 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) // with anything but its first input sample, shifts the phase and fails this. size_t decoded = 0; double error = 0, energy = 0; - std::optional first_decoded_us; + std::optional first_decoded; for (;;) { auto next = audio->next(); if (next.wait_for(std::chrono::seconds(10)) != std::future_status::ready) { @@ -281,11 +281,12 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) if (!variant) break; const auto *frame = &variant->frame; - if (!first_decoded_us) - first_decoded_us = frame->timestamp_us; + if (!first_decoded) + first_decoded = frame->timestamp; const auto *samples = reinterpret_cast(frame->data.data()); const size_t frames = frame->data.size() / sizeof(float) / channels; - const int64_t offset = static_cast(frame->timestamp_us * RATE / 1000000ULL) - (start + RATE); + const int64_t offset = + static_cast(frame->timestamp.value * RATE / frame->timestamp.scale) - (start + RATE); for (size_t i = 0; i < frames; i++) { const double expected = Tone(offset + static_cast(i)); for (size_t c = 0; c < channels; c++) { @@ -299,7 +300,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) // OBS never drains an audio encoder, so the decoder trims the 312-sample pre-skip // and nothing pads the tail: every input sample but that lookahead comes back. - CHECK(first_decoded_us == micros(0)); + // Compared as fractions of a second, since the track reads back at its own scale. + CHECK(first_decoded && first_decoded->value * RATE == sample(0) * first_decoded->scale); CHECK(decoded == count * encoder.frame_size - 312); CHECK(energy > 0 && error / energy < 0.05); printf(" %s, %zu channels: %zu samples, error %.4f\n", preset, channels, decoded, diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index dd758210273..49cd110f8b3 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -684,7 +684,8 @@ int main() // Everything up to the last frame, then the end of the track. bool ended = false; - uint64_t last_timestamp = first_frame ? first_frame->frame.timestamp_us : 0; + // Reads come back at the track's one scale, so values compare directly. + uint64_t last_timestamp = first_frame ? first_frame->frame.timestamp.value : 0; for (;;) { next = media->next(); if (next.wait_for(std::chrono::seconds(10)) != std::future_status::ready) @@ -698,10 +699,10 @@ int main() } CHECK(!std::holds_alternative((*result)->get_variant())); if (const auto *frame = std::get_if(&(*result)->get_variant())) - last_timestamp = frame->frame.timestamp_us; + last_timestamp = frame->frame.timestamp.value; } CHECK(ended); - CHECK(first_frame && last_timestamp > first_frame->frame.timestamp_us); + CHECK(first_frame && last_timestamp > first_frame->frame.timestamp.value); } } printf("stop drains the session: ok\n"); diff --git a/cpp/obs/test/moq-source-test.cpp b/cpp/obs/test/moq-source-test.cpp index 0a4fb13e0d7..85ce5d8943a 100644 --- a/cpp/obs/test/moq-source-test.cpp +++ b/cpp/obs/test/moq-source-test.cpp @@ -300,7 +300,8 @@ int g_decoded_width = 320; int g_decoded_height = 240; std::atomic g_last_decoder_extradata{-1}; std::atomic g_decoder_opens{0}; -// Only packets from the replacement use this timestamp; the old stream keeps decoding. +// Only packets from the replacement use this timestamp, in the nanoseconds packets carry; the +// old stream keeps decoding. std::atomic g_candidate_decode{0}; // 2: receive error, 3: needs more input std::atomic g_candidate_attempts{0}; // Holds packets' timestamps for reordering: each packet past the delay releases the @@ -376,7 +377,7 @@ int avcodec_send_packet(AVCodecContext *ctx, const AVPacket *packet) if (state.ready.size() >= g_decoder_capacity) return AVERROR(EAGAIN); state.last_pts = packet->pts; - if (state.last_pts == 1'000'000'000) + if (state.last_pts == 1'000'000'000'000) g_candidate_attempts++; state.held.push_back(packet->pts); if (state.held.size() > g_reorder_delay) { @@ -390,7 +391,7 @@ int avcodec_send_packet(AVCodecContext *ctx, const AVPacket *packet) int avcodec_receive_frame(AVCodecContext *ctx, AVFrame *frame) { auto &state = *static_cast(ctx->opaque); - if (state.last_pts == 1'000'000'000) { + if (state.last_pts == 1'000'000'000'000) { if (g_candidate_decode == 2) return AVERROR_INVALIDDATA; if (g_candidate_decode == 3) @@ -570,6 +571,12 @@ void report(const char *name) g_reported = g_failures; } +// A timestamp in microseconds, the scale most scenarios write at. +moq::Timestamp Micros(uint64_t us) +{ + return moq::Timestamp{us, 1'000'000}; +} + // A broadcast published on the relay, the way the MoQ output would publish it. class Publisher { public: @@ -606,9 +613,9 @@ class Publisher { { timestamp_us += 20'000; if (video) - TestOk(video->write_frame(moq::Frame{TestH264Keyframe(), timestamp_us}), "write video"); + TestOk(video->write_frame(moq::Frame{TestH264Keyframe(), Micros(timestamp_us)}), "write video"); if (audio) { - TestOk(audio->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, timestamp_us}), "write audio"); + TestOk(audio->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, Micros(timestamp_us)}), "write audio"); TestOk(audio->cut(), "cut audio"); } } @@ -807,33 +814,41 @@ int main() const auto *state = static_cast(held->video_decoder->codec_ctx->opaque); const auto pending = state->held.size(); CHECK(pending > 0); - const uint64_t end = static_cast(state->last_pts) + 1'000'000; + // The end and tail sit on a 90 kHz grid, which packets carry floored to nanoseconds. + const uint64_t end = static_cast(state->last_pts) * 9 / 100'000 + 90'000; + const auto ticks = [](uint64_t value) { + return moq::Timestamp{value, 90'000}; + }; + const auto nanos = [](uint64_t value) { + return value * 100'000 / 9; + }; auto inject = [&](moq::MediaRead read) { moq_source_on_frame(ctx, conn, held, std::optional{std::move(read)}); }; if (gap) { - inject(moq::MediaRead{moq::MediaRead::kGap{123456, std::chrono::microseconds(78901)}}); + inject(moq::MediaRead{ + moq::MediaRead::kGap{Micros(123456), std::chrono::microseconds(78901)}}); CHECK(g_output_frames == frames + static_cast(pending)); CHECK(!held->video_decoder->got_keyframe); } else { - inject(moq::MediaRead{moq::MediaRead::kEnd{end}}); + inject(moq::MediaRead{moq::MediaRead::kEnd{ticks(end)}}); CHECK(held->video_decoder->got_keyframe); // Non-key tail packets below the endpoint still depend on the old references. - inject(moq::MediaRead{ - moq::MediaRead::kFrame{moq::MediaFrame{TestH264Keyframe(), end - 1, false}}}); - CHECK(state->last_pts == static_cast(end - 1)); + inject(moq::MediaRead{moq::MediaRead::kFrame{ + moq::MediaFrame{TestH264Keyframe(), ticks(end - 1), false}}}); + CHECK(state->last_pts == static_cast(nanos(end - 1))); if (eof) { moq_source_on_frame(ctx, conn, held, std::optional{}); } else { inject(moq::MediaRead{moq::MediaRead::kFrame{ - moq::MediaFrame{TestH264Keyframe(), end, true}}}); - CHECK(state->last_pts == static_cast(end)); + moq::MediaFrame{TestH264Keyframe(), ticks(end), true}}}); + CHECK(state->last_pts == static_cast(nanos(end))); CHECK(state->held.size() == 1); } CHECK(g_output_frames == frames + static_cast(pending) + 1); std::lock_guard output_lock(g_video_mutex); CHECK(std::count(g_video_timestamps.begin(), g_video_timestamps.end(), - (end - 1) * 1000) == 1); + nanos(end - 1)) == 1); } CHECK(conn->video == held); } @@ -871,7 +886,8 @@ int main() }; for (int picture : decode_order) { const auto payload = picture == 0 ? TestH264Keyframe() : delta; - TestOk(publisher.video->write_frame(moq::Frame{payload, timestamp_us(picture)}), "write video"); + TestOk(publisher.video->write_frame(moq::Frame{payload, Micros(timestamp_us(picture))}), + "write video"); } TestOk(publisher.video->finish(), "finish video"); @@ -894,7 +910,7 @@ int main() const auto timestamp_us = [](int picture) { return 2'000'000 + uint64_t(picture) * 20'000; }; - g_unconverted_pts = int64_t(timestamp_us(2)); + g_unconverted_pts = int64_t(timestamp_us(2) * 1000); Publisher publisher(relay, "obs/test", true, false); void *source = createSource(); auto *ctx = static_cast(source); @@ -908,7 +924,8 @@ int main() std::vector expected; for (int picture = 0; picture < 6; picture++) { const auto payload = picture == 0 ? TestH264Keyframe() : delta; - TestOk(publisher.video->write_frame(moq::Frame{payload, timestamp_us(picture)}), "write video"); + TestOk(publisher.video->write_frame(moq::Frame{payload, Micros(timestamp_us(picture))}), + "write video"); expected.push_back(timestamp_us(picture) * 1000); } // Left unfinished: nothing is held back, and a finish appends an empty end-of-group frame. @@ -946,7 +963,8 @@ int main() }; CHECK(publisher.WriteUntil(pending)); // One picture, which the decoder holds until a drain. - TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), 1'000'000'000}), "replacement frame"); + TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), Micros(1'000'000'000)}), + "replacement frame"); TestOk(replacement->finish(), "finish replacement"); CHECK(publisher.WriteUntil([&] { return !pending(); })); const int frames = g_output_frames; @@ -973,7 +991,7 @@ int main() uint64_t samples = 0; CHECK(WaitFor([&] { for (const auto &frame : AAC_FRAMES) { - TestOk(aac->write_frame(moq::Frame{frame, 1'000'000 + samples * 1'000'000 / 44'100}), + TestOk(aac->write_frame(moq::Frame{frame, moq::Timestamp{44'100 + samples, 44'100}}), "write aac"); samples += 1024; } @@ -1389,7 +1407,7 @@ int main() const int frames = g_output_frames; CHECK(publisher.WriteUntil([&] { return g_output_frames >= frames + 10; })); CHECK(publisher.WriteUntil([&] { - TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), 2'000'000}), + TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), Micros(2'000'000)}), "replacement frame"); return g_last_timestamp == 2'000'000'000; })); @@ -1417,7 +1435,7 @@ int main() const auto preferring = CatalogPreferring(publisher, "!replacement"); DeliverCatalog(ctx, preferring); auto write = [&] { - TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), 1'000'000'000}), + TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), Micros(1'000'000'000)}), "replacement frame"); }; CHECK(publisher.WriteUntil([&] { @@ -1482,7 +1500,8 @@ int main() return true; })); CHECK(publisher.WriteUntil([&] { - TestOk(replacement->write_frame(moq::Frame{BAD_OPUS, 1'000'000'000}), "replacement frame"); + TestOk(replacement->write_frame(moq::Frame{BAD_OPUS, Micros(1'000'000'000)}), + "replacement frame"); TestOk(replacement->cut(), "replacement audio cut"); std::lock_guard lock(g_candidate_mutex); return g_candidate.failed && candidate.expired(); @@ -1523,7 +1542,7 @@ int main() pending = ctx->connection->pending_audio; return pending && pending->audio_consumer; })); - TestOk(publisher.audio->write_frame(moq::Frame{BAD_OPUS, 900'000'000}), "malformed frame"); + TestOk(publisher.audio->write_frame(moq::Frame{BAD_OPUS, Micros(900'000'000)}), "malformed frame"); TestOk(publisher.audio->cut(), "malformed cut"); CHECK(WaitFor([&] { std::lock_guard lock(ctx->mutex); @@ -1536,7 +1555,7 @@ int main() pending.reset(); uint64_t timestamp_us = 1'000'000'000; CHECK(WaitFor([&] { - TestOk(replacement->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, timestamp_us}), + TestOk(replacement->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, Micros(timestamp_us)}), "replacement frame"); TestOk(replacement->cut(), "replacement audio cut"); timestamp_us += 20'000; @@ -1563,7 +1582,7 @@ int main() CHECK(active != nullptr); obs_source_audio audio = {}; moq::expected> misaligned( - moq::AudioRead::kFrame{moq::AudioFrame{1, {0, 0, 0}}}); + moq::AudioRead::kFrame{moq::AudioFrame{Micros(1), {0, 0, 0}}}); CHECK(!moq_source_on_audio_read(ctx, conn, active, misaligned, audio)); CHECK(!conn->audio); } diff --git a/dart/moq/README.md b/dart/moq/README.md index 02fb4ec29a5..cff7d70ce40 100644 --- a/dart/moq/README.md +++ b/dart/moq/README.md @@ -45,8 +45,8 @@ await for (final request in server.requests()) { The package uses `Future` for asynchronous operations and `Stream` for announcements, and `connect` / `listen` take an options struct like Rust does. Types are spelled without the `Moq` prefix (`Session`, `BroadcastProducer`, -`Backoff`), and microsecond fields read back as a `Duration` (`stats.rtt`, -`frame.timestamp`). The lower-level generated API +`Backoff`). Spans cross as a `Duration` (`stats.rtt`), and media times as an +exact `Timestamp` with `toDuration()`. The lower-level generated API remains available through the re-exported `moq_ffi` package. Flutter Web is not supported. Browser applications should use the TypeScript diff --git a/dart/moq/bench/ffi.dart b/dart/moq/bench/ffi.dart index 0e55b1967f6..a4defdca85c 100644 --- a/dart/moq/bench/ffi.dart +++ b/dart/moq/bench/ffi.dart @@ -61,7 +61,7 @@ Future throughput( final frame = await group.readFrame(); require( frame != null && - frame.timestampUs == n * c.frames + f && + frame.timestamp?.value == n * c.frames + f && frame.payload.length == payload.length && memcmp(frame.payload.address, payload.address, payload.length) == 0, @@ -79,7 +79,10 @@ Future throughput( try { for (var f = 0; f < c.frames; f++) { group.writeFrame( - frame: Frame(payload: payload, timestampUs: n * c.frames + f), + frame: Frame( + payload: payload, + timestamp: Timestamp(value: n * c.frames + f, scale: 1000000), + ), ); } group.finish(); diff --git a/dart/moq/lib/audio.dart b/dart/moq/lib/audio.dart index da95989bec5..61d75cea7de 100644 --- a/dart/moq/lib/audio.dart +++ b/dart/moq/lib/audio.dart @@ -28,7 +28,7 @@ typedef ReadFrame = FrameMoqAudioRead; /// Media after what was already read was lost; what follows does not continue it. typedef ReadGap = GapMoqAudioRead; -/// The publisher stopped its encoder; frames starting before `endUs` are its remaining media. +/// The publisher stopped its encoder; frames starting before `end` are its remaining media. typedef ReadEnd = EndMoqAudioRead; /// The PCM layout written to a [Producer]. @@ -55,23 +55,5 @@ typedef Codec = MoqAudioCodec; /// A raw PCM sample layout. typedef SampleFormat = MoqAudioSampleFormat; -/// Duration view over a PCM frame's timestamp. -extension AudioFrameDuration on MoqAudioFrame { - /// Presentation timestamp of the first sample. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over a gap. -extension AudioReadGapDuration on GapMoqAudioRead { - /// The furthest presentation point already read. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over an encoder end. -extension AudioReadEndDuration on EndMoqAudioRead { - /// Where the stopped encoder's media stops. - Duration get end => Duration(microseconds: endUs); -} - /// Input, codec settings, and publication ownership for a producer. typedef ProducerOptions = MoqAudioProducerOptions; diff --git a/dart/moq/lib/json.dart b/dart/moq/lib/json.dart index a3df4dfb0c8..33c6efe5e47 100644 --- a/dart/moq/lib/json.dart +++ b/dart/moq/lib/json.dart @@ -41,9 +41,7 @@ typedef StreamProducer = MoqJsonStreamProducer; typedef StreamConsumer = MoqJsonStreamConsumer; /// A JSON string read from a track, with the timestamp of the frame that -/// carried it in microseconds, or null when untimed. Rounded down to a whole -/// microsecond, so a tick on a track like 90 kHz may not survive a read and -/// republish exactly. +/// carried it, or null when untimed. typedef Value = MoqJsonValue; /// Publishes a sliding window of JSON records on a track it takes over, pushed @@ -70,6 +68,6 @@ typedef WindowEventPop = PopMoqJsonWindowEvent; /// The records in `[start, end)` will never be delivered to this reader. typedef WindowEventSkip = SkipMoqJsonWindowEvent; -/// A [WindowEvent] and the timestamp of the frame that carried it, in -/// microseconds, or null when untimed. +/// A [WindowEvent] and the timestamp of the frame that carried it, or null +/// when untimed. typedef WindowTimed = MoqJsonWindowTimed; diff --git a/dart/moq/lib/media.dart b/dart/moq/lib/media.dart index 0238b8b70ef..aa03b240d80 100644 --- a/dart/moq/lib/media.dart +++ b/dart/moq/lib/media.dart @@ -110,21 +110,3 @@ typedef GroupConfig = MoqMediaGroupConfig; /// The packaging advertised for a media track. typedef Container = MoqContainer; - -/// Duration view over a media frame's presentation time. -extension MediaFrameDuration on MoqMediaFrame { - /// Presentation timestamp. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over a gap. -extension MediaReadGapDuration on GapMoqMediaRead { - /// The furthest presentation point already read. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over an encoder end. -extension MediaReadEndDuration on EndMoqMediaRead { - /// Where the stopped encoder's media stops. - Duration get end => Duration(microseconds: endUs); -} diff --git a/dart/moq/lib/moq.dart b/dart/moq/lib/moq.dart index 7bdaaaf25da..25bbc4f11f9 100644 --- a/dart/moq/lib/moq.dart +++ b/dart/moq/lib/moq.dart @@ -5,6 +5,6 @@ export 'package:moq_ffi/moq_ffi.dart'; export 'src/aliases.dart'; export 'src/client.dart'; -export 'src/durations.dart'; export 'src/epoch.dart'; export 'src/server.dart'; +export 'src/timestamp.dart'; diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 7610865c8db..b508a1c114e 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -131,6 +131,9 @@ typedef Datagram = MoqDatagram; /// A payload plus the timestamp it should be presented at. typedef Frame = MoqFrame; +/// An exact media time: `value` units at `scale` units per second. +typedef Timestamp = MoqTimestamp; + /// Tunes how a track subscription is delivered: priority, latency budget, ranges, and group ordering. typedef Subscription = MoqSubscription; diff --git a/dart/moq/lib/src/durations.dart b/dart/moq/lib/src/durations.dart deleted file mode 100644 index 386dd2ca476..00000000000 --- a/dart/moq/lib/src/durations.dart +++ /dev/null @@ -1,20 +0,0 @@ -import 'package:moq_ffi/moq_ffi.dart'; - -// The FFI surface carries media timestamps as microsecond integers; durations -// already cross as Dart's Duration. Read the timestamps back as a Duration. -// These are extensions, so the `*Us` fields stay available for anyone building -// a record to send back across the boundary. - -/// Duration view over a raw frame's presentation time. -extension FrameDuration on MoqFrame { - /// Presentation timestamp, or null for an untimed frame. - Duration? get timestamp => - timestampUs == null ? null : Duration(microseconds: timestampUs!); -} - -/// Duration view over a datagram's presentation time. -extension DatagramDuration on MoqDatagram { - /// Presentation timestamp, or null for an untimed datagram. - Duration? get timestamp => - timestampUs == null ? null : Duration(microseconds: timestampUs!); -} diff --git a/dart/moq/lib/src/timestamp.dart b/dart/moq/lib/src/timestamp.dart new file mode 100644 index 00000000000..67dcbe62a45 --- /dev/null +++ b/dart/moq/lib/src/timestamp.dart @@ -0,0 +1,37 @@ +import 'package:moq_ffi/moq_ffi.dart'; + +final _microsPerSecond = BigInt.from(Duration.microsecondsPerSecond); + +/// Converts a [MoqTimestamp] to Dart's [Duration]. +extension TimestampDuration on MoqTimestamp { + /// This timestamp as a [Duration], rounded down to a whole microsecond. + /// + /// The timestamp itself is exact; keep it, not the duration, to republish a + /// tick such as 90 kHz. Throws a [RangeError] when the result does not fit + /// in a [Duration]. + Duration toDuration() { + // value * 10^6 can exceed 64 bits at the allowed bounds. + final units = BigInt.from(scale); + final micros = BigInt.from(value) * _microsPerSecond ~/ units; + if (!micros.isValidInt) { + throw RangeError('timestamp $value/$scale s does not fit in a Duration'); + } + return Duration(microseconds: micros.toInt()); + } +} + +/// Converts a [Duration] to an exact [MoqTimestamp]. +extension DurationTimestamp on Duration { + /// This duration as an exact timestamp at microsecond scale. + /// + /// Throws an [ArgumentError] when negative. + MoqTimestamp toTimestamp() { + if (isNegative) { + throw ArgumentError.value(this, 'duration', 'must not be negative'); + } + return MoqTimestamp( + value: inMicroseconds, + scale: Duration.microsecondsPerSecond, + ); + } +} diff --git a/dart/moq/lib/video.dart b/dart/moq/lib/video.dart index 0d220a93aaa..1de2a0ac6d6 100644 --- a/dart/moq/lib/video.dart +++ b/dart/moq/lib/video.dart @@ -82,30 +82,6 @@ typedef SoftwareEncoder = SoftwareMoqVideoEncoderKind; /// A specific backend by name, such as `videotoolbox`, `mediafoundation`, or `openh264`. typedef NamedEncoder = NamedMoqVideoEncoderKind; -/// Duration view over a raw picture's timestamp. -extension VideoFrameDuration on MoqVideoFrame { - /// Presentation timestamp. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over a decoded picture's timestamp. -extension VideoDecodedFrameDuration on MoqVideoDecodedFrame { - /// Presentation timestamp. - Duration get timestamp => Duration(microseconds: timestampUs()); -} - -/// Duration view over a gap. -extension VideoReadGapDuration on GapMoqVideoRead { - /// The furthest presentation point already read. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over an encoder end. -extension VideoReadEndDuration on EndMoqVideoRead { - /// Where the stopped encoder's media stops. - Duration get end => Duration(microseconds: endUs); -} - /// Input, codec settings, and publication ownership for a producer. typedef ProducerOptions = MoqVideoProducerOptions; diff --git a/dart/moq/test/docs/prelude.dart b/dart/moq/test/docs/prelude.dart index 02c1f7b750b..a76e2c48b14 100644 --- a/dart/moq/test/docs/prelude.dart +++ b/dart/moq/test/docs/prelude.dart @@ -6,4 +6,4 @@ import 'package:moq/moq.dart'; Moq get moq => throw UnimplementedError(); Uint8List get bytes => throw UnimplementedError(); Uint8List get rgba => throw UnimplementedError(); -int get pts => throw UnimplementedError(); +Timestamp get pts => throw UnimplementedError(); diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 025d8538ae8..6360596ae93 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -61,7 +61,7 @@ void main() { final consumer = track.consume(subscription: null); track.writeFrame(frame: Frame(payload: utf8.encode('payload'))); final frame = await consumer.readFrame().timeout(timeout); - expect(frame?.timestampUs, isNull); + expect(frame?.timestamp, isNull); expect(consumer.info().timescale, isNull); track.finish(); broadcast.close(); @@ -95,7 +95,10 @@ void main() { for (var ms = 0; ms < 3; ms++) { final group = track.appendGroup(); group.writeFrame( - frame: Frame(payload: utf8.encode('x'), timestampUs: ms * 1000), + frame: Frame( + payload: utf8.encode('x'), + timestamp: Duration(milliseconds: ms).toTimestamp(), + ), ); group.finish(); } @@ -236,7 +239,10 @@ void main() { final producer = track.appendGroup(); producer.writeFrame( - frame: MoqFrame(payload: utf8.encode('dart round trip'), timestampUs: 0), + frame: MoqFrame( + payload: utf8.encode('dart round trip'), + timestamp: Duration.zero.toTimestamp(), + ), ); producer.finish(); @@ -387,14 +393,60 @@ void main() { expect(() => catalog.finish(), throwsA(isA())); }); - test('microsecond timestamps read back as Durations', () { + test('timestamps round-trip exactly at the track scale', () async { + final broadcast = BroadcastProducer(); + final track = broadcast.publishTrack( + name: 'video', + info: TrackInfo(timescale: 90000), + ); + final consumer = track.consume(subscription: null); + // A present zero stays present, and one 90 kHz tick reads back as itself + // rather than the 11 us a microsecond field floors it to. + for (final value in [0, 1]) { + track.writeFrame( + frame: Frame( + payload: utf8.encode('frame'), + timestamp: Timestamp(value: value, scale: 90000), + ), + ); + final frame = await consumer.readFrame().timeout(timeout); + expect(frame?.timestamp?.value, value); + expect(frame?.timestamp?.scale, 90000); + } + + for (final invalid in [ + Timestamp(value: 0, scale: 0), + Timestamp(value: 0, scale: 1 << 62), + Timestamp(value: 1 << 61, scale: 90000), + ]) { + expect( + () => track.writeFrame( + frame: Frame(payload: utf8.encode('frame'), timestamp: invalid), + ), + throwsA(isA()), + ); + } + track.finish(); + broadcast.close(); + }); + + test('timestamps convert to and from Durations', () { + final exact = const Duration(milliseconds: 20).toTimestamp(); + expect([exact.value, exact.scale], [20000, 1000000]); + expect(exact.toDuration(), const Duration(milliseconds: 20)); + // 5 ticks at 90 kHz is 55.6 us, and half a microsecond is 0.5: both round down. expect( - Frame(payload: Uint8List(0), timestampUs: 20000).timestamp, - const Duration(milliseconds: 20), + Timestamp(value: 5, scale: 90000).toDuration(), + const Duration(microseconds: 55), ); + expect(Timestamp(value: 1, scale: 2000000).toDuration(), Duration.zero); expect( - moq_video.Frame(timestampUs: 33333, data: Uint8List(0)).timestamp, - const Duration(microseconds: 33333), + () => Timestamp(value: (1 << 61) - 1, scale: 1).toDuration(), + throwsRangeError, + ); + expect( + () => const Duration(microseconds: -1).toTimestamp(), + throwsArgumentError, ); }); @@ -524,18 +576,21 @@ void main() { final consumer = moq_json.SnapshotConsumer(track: track); for (var n = 1; n <= 4; n++) { - producer.update(value: jsonEncode({'n': n}), timestampUs: n * 1000); + producer.update( + value: jsonEncode({'n': n}), + timestamp: Duration(milliseconds: n).toTimestamp(), + ); } // next() yields every state in order; latest() skips the buffered third. moq_json.Value? value = await consumer.next().timeout(timeout); expect(jsonDecode(value!.value), {'n': 1}); - expect(value.timestampUs, 1000); + expect(value.timestamp?.toDuration(), const Duration(milliseconds: 1)); value = await consumer.next().timeout(timeout); expect(jsonDecode(value!.value), {'n': 2}); value = await consumer.latest().timeout(timeout); expect(jsonDecode(value!.value), {'n': 4}); - expect(value.timestampUs, 4000); + expect(value.timestamp?.toDuration(), const Duration(milliseconds: 4)); consumer.cancel(); producer.finish(); @@ -558,29 +613,38 @@ void main() { final consumer = moq_json.WindowConsumer(track: track); for (var n = 0; n < 3; n++) { - producer.push(value: jsonEncode({'n': n}), timestampUs: n * 1000); + producer.push( + value: jsonEncode({'n': n}), + timestamp: Duration(milliseconds: n).toTimestamp(), + ); } - producer.pop(count: 2, timestampUs: 3000); + producer.pop( + count: 2, + timestamp: const Duration(milliseconds: 3).toTimestamp(), + ); for (var n = 0; n < 3; n++) { final timed = await consumer.next().timeout(timeout); final push = timed!.event as moq_json.WindowEventPush; expect(push.index, n); expect(jsonDecode(push.value), {'n': n}); - expect(timed.timestampUs, n * 1000); + expect(timed.timestamp?.toDuration(), Duration(milliseconds: n)); } final timed = await consumer.next().timeout(timeout); final pop = timed!.event as moq_json.WindowEventPop; expect([pop.start, pop.end], [0, 2]); - expect(timed.timestampUs, 3000); + expect(timed.timestamp?.toDuration(), const Duration(milliseconds: 3)); // The cut's new group restates record 2, which this reader already has. producer.cut(); - producer.push(value: jsonEncode({'n': 3}), timestampUs: 4000); + producer.push( + value: jsonEncode({'n': 3}), + timestamp: const Duration(milliseconds: 4).toTimestamp(), + ); final pushed = await consumer.next().timeout(timeout); final push = pushed!.event as moq_json.WindowEventPush; expect(push.index, 3); - expect(pushed.timestampUs, 4000); + expect(pushed.timestamp?.toDuration(), const Duration(milliseconds: 4)); producer.finish(); expect(await consumer.next().timeout(timeout), isNull); @@ -612,7 +676,10 @@ void main() { video.cut(); for (var i = 0; i < 10; i++) { video.write( - frame: moq_video.Frame(timestampUs: i * 33333, data: rgba), + frame: moq_video.Frame( + timestamp: Timestamp(value: i * 3003, scale: 90000), + data: rgba, + ), ); } @@ -631,7 +698,10 @@ void main() { // Keep the encoder fed so the decoder sees frames after it joined. for (var i = 10; i < 40; i++) { video.write( - frame: moq_video.Frame(timestampUs: i * 33333, data: rgba), + frame: moq_video.Frame( + timestamp: Timestamp(value: i * 3003, scale: 90000), + data: rgba, + ), ); } @@ -706,7 +776,7 @@ void main() { for (var i = 0; i < 2; i++) { audio.write( frame: moq_audio.Frame( - timestampUs: i * 20000, + timestamp: Duration(milliseconds: i * 20).toTimestamp(), data: Uint8List(960 * 4), ), ); @@ -742,7 +812,10 @@ void main() { ), ); producer.write( - frame: moq_audio.Frame(timestampUs: 0, data: Uint8List(960 * 4)), + frame: moq_audio.Frame( + timestamp: Duration.zero.toTimestamp(), + data: Uint8List(960 * 4), + ), ); expect(producer.demand().name(), 'mic'); producer.finish(); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 64ecbf455ab..f669299b304 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -382,9 +382,9 @@ class FfiConverterMoqAudioEncoderOutput { } class MoqAudioFrame { - final int timestampUs; + final MoqTimestamp timestamp; final Uint8List data; - MoqAudioFrame({required this.timestampUs, required this.data}); + MoqAudioFrame({required this.timestamp, required this.data}); } class FfiConverterMoqAudioFrame { @@ -394,25 +394,25 @@ class FfiConverterMoqAudioFrame { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final data_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); final data = data_lifted.value; new_offset += data_lifted.bytesRead; return LiftRetVal( - MoqAudioFrame(timestampUs: timestampUs, data: data), + MoqAudioFrame(timestamp: timestamp, data: data), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqAudioFrame value) { final total_length = - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; final buf = Uint8List(total_length); @@ -422,8 +422,8 @@ class FfiConverterMoqAudioFrame { static int write(MoqAudioFrame value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -434,7 +434,7 @@ class FfiConverterMoqAudioFrame { } static int allocationSize(MoqAudioFrame value) { - return FfiConverterUInt64.allocationSize(value.timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; } @@ -998,8 +998,8 @@ class FfiConverterMoqJsonSnapshotConfig { class MoqJsonValue { final String value; - final int? timestampUs; - MoqJsonValue({required this.value, this.timestampUs}); + final MoqTimestamp? timestamp; + MoqJsonValue({required this.value, this.timestamp}); } class FfiConverterMoqJsonValue { @@ -1014,13 +1014,13 @@ class FfiConverterMoqJsonValue { ); final value = value_lifted.value; new_offset += value_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; return LiftRetVal( - MoqJsonValue(value: value, timestampUs: timestampUs), + MoqJsonValue(value: value, timestamp: timestamp), new_offset - buf.offsetInBytes, ); } @@ -1028,7 +1028,7 @@ class FfiConverterMoqJsonValue { static RustBuffer lower(MoqJsonValue value) { final total_length = FfiConverterString.allocationSize(value.value) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -1041,8 +1041,8 @@ class FfiConverterMoqJsonValue { value.value, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset - buf.offsetInBytes; @@ -1050,7 +1050,7 @@ class FfiConverterMoqJsonValue { static int allocationSize(MoqJsonValue value) { return FfiConverterString.allocationSize(value.value) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; } } @@ -1103,8 +1103,8 @@ class FfiConverterMoqJsonWindowConfig { class MoqJsonWindowTimed { final MoqJsonWindowEvent event; - final int? timestampUs; - MoqJsonWindowTimed({required this.event, this.timestampUs}); + final MoqTimestamp? timestamp; + MoqJsonWindowTimed({required this.event, this.timestamp}); } class FfiConverterMoqJsonWindowTimed { @@ -1119,13 +1119,13 @@ class FfiConverterMoqJsonWindowTimed { ); final event = event_lifted.value; new_offset += event_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; return LiftRetVal( - MoqJsonWindowTimed(event: event, timestampUs: timestampUs), + MoqJsonWindowTimed(event: event, timestamp: timestamp), new_offset - buf.offsetInBytes, ); } @@ -1133,7 +1133,7 @@ class FfiConverterMoqJsonWindowTimed { static RustBuffer lower(MoqJsonWindowTimed value) { final total_length = FfiConverterMoqJsonWindowEvent.allocationSize(value.event) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -1146,8 +1146,8 @@ class FfiConverterMoqJsonWindowTimed { value.event, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset - buf.offsetInBytes; @@ -1155,7 +1155,7 @@ class FfiConverterMoqJsonWindowTimed { static int allocationSize(MoqJsonWindowTimed value) { return FfiConverterMoqJsonWindowEvent.allocationSize(value.event) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; } } @@ -1634,11 +1634,11 @@ class FfiConverterMoqContainerInit { class MoqDatagram { final int sequence; - final int? timestampUs; + final MoqTimestamp? timestamp; final Uint8List payload; MoqDatagram({ this.sequence = 0, - this.timestampUs = null, + this.timestamp = null, required this.payload, }); } @@ -1655,22 +1655,18 @@ class FfiConverterMoqDatagram { ); final sequence = sequence_lifted.value; new_offset += sequence_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final payload_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); final payload = payload_lifted.value; new_offset += payload_lifted.bytesRead; return LiftRetVal( - MoqDatagram( - sequence: sequence, - timestampUs: timestampUs, - payload: payload, - ), + MoqDatagram(sequence: sequence, timestamp: timestamp, payload: payload), new_offset - buf.offsetInBytes, ); } @@ -1678,7 +1674,7 @@ class FfiConverterMoqDatagram { static RustBuffer lower(MoqDatagram value) { final total_length = FfiConverterUInt64.allocationSize(value.sequence) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.payload) + 0; final buf = Uint8List(total_length); @@ -1692,8 +1688,8 @@ class FfiConverterMoqDatagram { value.sequence, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -1705,7 +1701,7 @@ class FfiConverterMoqDatagram { static int allocationSize(MoqDatagram value) { return FfiConverterUInt64.allocationSize(value.sequence) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.payload) + 0; } @@ -1831,8 +1827,8 @@ class FfiConverterMoqDimensions { class MoqFrame { final Uint8List payload; - final int? timestampUs; - MoqFrame({required this.payload, this.timestampUs = null}); + final MoqTimestamp? timestamp; + MoqFrame({required this.payload, this.timestamp = null}); } class FfiConverterMoqFrame { @@ -1847,13 +1843,13 @@ class FfiConverterMoqFrame { ); final payload = payload_lifted.value; new_offset += payload_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; return LiftRetVal( - MoqFrame(payload: payload, timestampUs: timestampUs), + MoqFrame(payload: payload, timestamp: timestamp), new_offset - buf.offsetInBytes, ); } @@ -1861,7 +1857,7 @@ class FfiConverterMoqFrame { static RustBuffer lower(MoqFrame value) { final total_length = FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -1874,8 +1870,8 @@ class FfiConverterMoqFrame { value.payload, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset - buf.offsetInBytes; @@ -1883,18 +1879,18 @@ class FfiConverterMoqFrame { static int allocationSize(MoqFrame value) { return FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; } } class MoqMediaFrame { final Uint8List payload; - final int timestampUs; + final MoqTimestamp timestamp; final bool keyframe; MoqMediaFrame({ required this.payload, - required this.timestampUs, + required this.timestamp, required this.keyframe, }); } @@ -1911,22 +1907,18 @@ class FfiConverterMoqMediaFrame { ); final payload = payload_lifted.value; new_offset += payload_lifted.bytesRead; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final keyframe_lifted = FfiConverterBool.read( Uint8List.view(buf.buffer, new_offset), ); final keyframe = keyframe_lifted.value; new_offset += keyframe_lifted.bytesRead; return LiftRetVal( - MoqMediaFrame( - payload: payload, - timestampUs: timestampUs, - keyframe: keyframe, - ), + MoqMediaFrame(payload: payload, timestamp: timestamp, keyframe: keyframe), new_offset - buf.offsetInBytes, ); } @@ -1934,7 +1926,7 @@ class FfiConverterMoqMediaFrame { static RustBuffer lower(MoqMediaFrame value) { final total_length = FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterBool.allocationSize(value.keyframe) + 0; final buf = Uint8List(total_length); @@ -1948,8 +1940,8 @@ class FfiConverterMoqMediaFrame { value.payload, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterBool.write( @@ -1961,7 +1953,7 @@ class FfiConverterMoqMediaFrame { static int allocationSize(MoqMediaFrame value) { return FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterBool.allocationSize(value.keyframe) + 0; } @@ -2105,6 +2097,65 @@ class FfiConverterMoqMediaTrackConfig { } } +class MoqTimestamp { + final int value; + final int scale; + MoqTimestamp({required this.value, required this.scale}); +} + +class FfiConverterMoqTimestamp { + static MoqTimestamp lift(RustBuffer buf) { + return FfiConverterMoqTimestamp.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final value_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final value = value_lifted.value; + new_offset += value_lifted.bytesRead; + final scale_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final scale = scale_lifted.value; + new_offset += scale_lifted.bytesRead; + return LiftRetVal( + MoqTimestamp(value: value, scale: scale), + new_offset - buf.offsetInBytes, + ); + } + + static RustBuffer lower(MoqTimestamp value) { + final total_length = + FfiConverterUInt64.allocationSize(value.value) + + FfiConverterUInt64.allocationSize(value.scale) + + 0; + final buf = Uint8List(total_length); + write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqTimestamp value, Uint8List buf) { + int new_offset = buf.offsetInBytes; + new_offset += FfiConverterUInt64.write( + value.value, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterUInt64.write( + value.scale, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset - buf.offsetInBytes; + } + + static int allocationSize(MoqTimestamp value) { + return FfiConverterUInt64.allocationSize(value.value) + + FfiConverterUInt64.allocationSize(value.scale) + + 0; + } +} + class MoqVideo { final String? label; final String? broadcast; @@ -4533,9 +4584,9 @@ class FfiConverterMoqVideoEncoderOutput { } class MoqVideoFrame { - final int timestampUs; + final MoqTimestamp timestamp; final Uint8List data; - MoqVideoFrame({required this.timestampUs, required this.data}); + MoqVideoFrame({required this.timestamp, required this.data}); } class FfiConverterMoqVideoFrame { @@ -4545,25 +4596,25 @@ class FfiConverterMoqVideoFrame { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final data_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); final data = data_lifted.value; new_offset += data_lifted.bytesRead; return LiftRetVal( - MoqVideoFrame(timestampUs: timestampUs, data: data), + MoqVideoFrame(timestamp: timestamp, data: data), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqVideoFrame value) { final total_length = - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; final buf = Uint8List(total_length); @@ -4573,8 +4624,8 @@ class FfiConverterMoqVideoFrame { static int write(MoqVideoFrame value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -4585,7 +4636,7 @@ class FfiConverterMoqVideoFrame { } static int allocationSize(MoqVideoFrame value) { - return FfiConverterUInt64.allocationSize(value.timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; } @@ -4651,11 +4702,11 @@ class FfiConverterMoqVideoFrameRate { } class MoqVideoPacket { - final int timestampUs; + final MoqTimestamp timestamp; final Uint8List data; final bool keyframe; MoqVideoPacket({ - required this.timestampUs, + required this.timestamp, required this.data, required this.keyframe, }); @@ -4668,11 +4719,11 @@ class FfiConverterMoqVideoPacket { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final data_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); @@ -4684,14 +4735,14 @@ class FfiConverterMoqVideoPacket { final keyframe = keyframe_lifted.value; new_offset += keyframe_lifted.bytesRead; return LiftRetVal( - MoqVideoPacket(timestampUs: timestampUs, data: data, keyframe: keyframe), + MoqVideoPacket(timestamp: timestamp, data: data, keyframe: keyframe), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqVideoPacket value) { final total_length = - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + FfiConverterBool.allocationSize(value.keyframe) + 0; @@ -4702,8 +4753,8 @@ class FfiConverterMoqVideoPacket { static int write(MoqVideoPacket value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -4718,7 +4769,7 @@ class FfiConverterMoqVideoPacket { } static int allocationSize(MoqVideoPacket value) { - return FfiConverterUInt64.allocationSize(value.timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + FfiConverterBool.allocationSize(value.keyframe) + 0; @@ -4925,26 +4976,26 @@ class FrameMoqAudioRead extends MoqAudioRead { } class GapMoqAudioRead extends MoqAudioRead { - final int timestampUs; + final MoqTimestamp timestamp; final Duration duration; GapMoqAudioRead({ - required int this.timestampUs, + required MoqTimestamp this.timestamp, required Duration this.duration, }); - GapMoqAudioRead._(int this.timestampUs, Duration this.duration); + GapMoqAudioRead._(MoqTimestamp this.timestamp, Duration this.duration); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final duration_lifted = FfiConverterDuration.read( Uint8List.view(buf.buffer, new_offset), ); final duration = duration_lifted.value; new_offset += duration_lifted.bytesRead; - return LiftRetVal(GapMoqAudioRead._(timestampUs, duration), new_offset); + return LiftRetVal(GapMoqAudioRead._(timestamp, duration), new_offset); } @override @@ -4956,7 +5007,7 @@ class GapMoqAudioRead extends MoqAudioRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(timestamp) + FfiConverterDuration.allocationSize(duration) + 4; } @@ -4965,8 +5016,8 @@ class GapMoqAudioRead extends MoqAudioRead { int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 2); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterDuration.write( @@ -4978,17 +5029,17 @@ class GapMoqAudioRead extends MoqAudioRead { } class EndMoqAudioRead extends MoqAudioRead { - final int endUs; - EndMoqAudioRead(int this.endUs); - EndMoqAudioRead._(int this.endUs); + final MoqTimestamp end; + EndMoqAudioRead(MoqTimestamp this.end); + EndMoqAudioRead._(MoqTimestamp this.end); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final endUs_lifted = FfiConverterUInt64.read( + final end_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final endUs = endUs_lifted.value; - new_offset += endUs_lifted.bytesRead; - return LiftRetVal(EndMoqAudioRead._(endUs), new_offset); + final end = end_lifted.value; + new_offset += end_lifted.bytesRead; + return LiftRetVal(EndMoqAudioRead._(end), new_offset); } @override @@ -5000,15 +5051,15 @@ class EndMoqAudioRead extends MoqAudioRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(endUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(end) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - endUs, + new_offset += FfiConverterMoqTimestamp.write( + end, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -5203,17 +5254,17 @@ class RelativeMoqAnchor extends MoqAnchor { } class TimeMoqAnchor extends MoqAnchor { - final int timestampUs; - TimeMoqAnchor(int this.timestampUs); - TimeMoqAnchor._(int this.timestampUs); + final MoqTimestamp timestamp; + TimeMoqAnchor(MoqTimestamp this.timestamp); + TimeMoqAnchor._(MoqTimestamp this.timestamp); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; - return LiftRetVal(TimeMoqAnchor._(timestampUs), new_offset); + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; + return LiftRetVal(TimeMoqAnchor._(timestamp), new_offset); } @override @@ -5225,15 +5276,15 @@ class TimeMoqAnchor extends MoqAnchor { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(timestamp) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -7397,26 +7448,26 @@ class FrameMoqMediaRead extends MoqMediaRead { } class GapMoqMediaRead extends MoqMediaRead { - final int timestampUs; + final MoqTimestamp timestamp; final Duration duration; GapMoqMediaRead({ - required int this.timestampUs, + required MoqTimestamp this.timestamp, required Duration this.duration, }); - GapMoqMediaRead._(int this.timestampUs, Duration this.duration); + GapMoqMediaRead._(MoqTimestamp this.timestamp, Duration this.duration); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final duration_lifted = FfiConverterDuration.read( Uint8List.view(buf.buffer, new_offset), ); final duration = duration_lifted.value; new_offset += duration_lifted.bytesRead; - return LiftRetVal(GapMoqMediaRead._(timestampUs, duration), new_offset); + return LiftRetVal(GapMoqMediaRead._(timestamp, duration), new_offset); } @override @@ -7428,7 +7479,7 @@ class GapMoqMediaRead extends MoqMediaRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(timestamp) + FfiConverterDuration.allocationSize(duration) + 4; } @@ -7437,8 +7488,8 @@ class GapMoqMediaRead extends MoqMediaRead { int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 2); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterDuration.write( @@ -7450,17 +7501,17 @@ class GapMoqMediaRead extends MoqMediaRead { } class EndMoqMediaRead extends MoqMediaRead { - final int endUs; - EndMoqMediaRead(int this.endUs); - EndMoqMediaRead._(int this.endUs); + final MoqTimestamp end; + EndMoqMediaRead(MoqTimestamp this.end); + EndMoqMediaRead._(MoqTimestamp this.end); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final endUs_lifted = FfiConverterUInt64.read( + final end_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final endUs = endUs_lifted.value; - new_offset += endUs_lifted.bytesRead; - return LiftRetVal(EndMoqMediaRead._(endUs), new_offset); + final end = end_lifted.value; + new_offset += end_lifted.bytesRead; + return LiftRetVal(EndMoqMediaRead._(end), new_offset); } @override @@ -7472,15 +7523,15 @@ class EndMoqMediaRead extends MoqMediaRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(endUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(end) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - endUs, + new_offset += FfiConverterMoqTimestamp.write( + end, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -8639,26 +8690,26 @@ class FrameMoqVideoRead extends MoqVideoRead { } class GapMoqVideoRead extends MoqVideoRead { - final int timestampUs; + final MoqTimestamp timestamp; final Duration duration; GapMoqVideoRead({ - required int this.timestampUs, + required MoqTimestamp this.timestamp, required Duration this.duration, }); - GapMoqVideoRead._(int this.timestampUs, Duration this.duration); + GapMoqVideoRead._(MoqTimestamp this.timestamp, Duration this.duration); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final duration_lifted = FfiConverterDuration.read( Uint8List.view(buf.buffer, new_offset), ); final duration = duration_lifted.value; new_offset += duration_lifted.bytesRead; - return LiftRetVal(GapMoqVideoRead._(timestampUs, duration), new_offset); + return LiftRetVal(GapMoqVideoRead._(timestamp, duration), new_offset); } @override @@ -8670,7 +8721,7 @@ class GapMoqVideoRead extends MoqVideoRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(timestamp) + FfiConverterDuration.allocationSize(duration) + 4; } @@ -8679,8 +8730,8 @@ class GapMoqVideoRead extends MoqVideoRead { int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 2); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterDuration.write( @@ -8692,17 +8743,17 @@ class GapMoqVideoRead extends MoqVideoRead { } class EndMoqVideoRead extends MoqVideoRead { - final int endUs; - EndMoqVideoRead(int this.endUs); - EndMoqVideoRead._(int this.endUs); + final MoqTimestamp end; + EndMoqVideoRead(MoqTimestamp this.end); + EndMoqVideoRead._(MoqTimestamp this.end); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final endUs_lifted = FfiConverterUInt64.read( + final end_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final endUs = endUs_lifted.value; - new_offset += endUs_lifted.bytesRead; - return LiftRetVal(EndMoqVideoRead._(endUs), new_offset); + final end = end_lifted.value; + new_offset += end_lifted.bytesRead; + return LiftRetVal(EndMoqVideoRead._(end), new_offset); } @override @@ -8714,15 +8765,15 @@ class EndMoqVideoRead extends MoqVideoRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(endUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(end) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - endUs, + new_offset += FfiConverterMoqTimestamp.write( + end, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -10247,7 +10298,7 @@ class FfiConverterMoqJsonSnapshotConsumer { abstract class MoqJsonSnapshotProducerInterface { MoqTrackDemand demand(); void finish(); - void update({required String value, int? timestampUs = null}); + void update({required String value, MoqTimestamp? timestamp = null}); } final _MoqJsonSnapshotProducerFinalizer = Finalizer>((ptr) { @@ -10320,12 +10371,12 @@ class MoqJsonSnapshotProducer implements MoqJsonSnapshotProducerInterface { }, moqExceptionErrorHandler); } - void update({required String value, int? timestampUs = null}) { + void update({required String value, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10459,7 +10510,7 @@ class FfiConverterMoqJsonStreamConsumer { } abstract class MoqJsonStreamProducerInterface { - void append({required String value, int? timestampUs = null}); + void append({required String value, MoqTimestamp? timestamp = null}); MoqTrackDemand demand(); void finish(); } @@ -10512,12 +10563,12 @@ class MoqJsonStreamProducer implements MoqJsonStreamProducerInterface { ); } - void append({required String value, int? timestampUs = null}) { + void append({required String value, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10674,8 +10725,8 @@ abstract class MoqJsonWindowProducerInterface { void cut(); MoqTrackDemand demand(); void finish(); - void pop({required int count, int? timestampUs = null}); - void push({required String value, int? timestampUs = null}); + void pop({required int count, MoqTimestamp? timestamp = null}); + void push({required String value, MoqTimestamp? timestamp = null}); } final _MoqJsonWindowProducerFinalizer = Finalizer>((ptr) { @@ -10755,23 +10806,23 @@ class MoqJsonWindowProducer implements MoqJsonWindowProducerInterface { }, moqExceptionErrorHandler); } - void pop({required int count, int? timestampUs = null}) { + void pop({required int count, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( uniffiClonePointer(), FfiConverterUInt64.lower(count), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); } - void push({required String value, int? timestampUs = null}) { + void push({required String value, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonwindowproducer_push( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10913,7 +10964,7 @@ class FfiConverterMoqMediaCatalogConsumer { abstract class MoqMediaCatalogProducerInterface { void finish(); - int now(); + MoqTimestamp now(); void removeSection({required String name}); void setSection({required String name, required String json}); void setVideoProperties({required MoqVideoProperties properties}); @@ -10973,13 +11024,13 @@ class MoqMediaCatalogProducer implements MoqMediaCatalogProducerInterface { }, moqExceptionErrorHandler); } - int now() { + MoqTimestamp now() { return rustCallWithLifter( (status) => uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( uniffiClonePointer(), status, ), - FfiConverterUInt64.lift, + FfiConverterMoqTimestamp.lift, moqExceptionErrorHandler, ); } @@ -14253,7 +14304,7 @@ abstract class MoqVideoDecodedFrameInterface { int height(); Uint8List pixels({required MoqVideoPixelFormat format}); MoqVideoSurface? surface(); - int timestampUs(); + MoqTimestamp timestamp(); int width(); } @@ -14326,13 +14377,13 @@ class MoqVideoDecodedFrame implements MoqVideoDecodedFrameInterface { ); } - int timestampUs() { + MoqTimestamp timestamp() { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp_us( + (status) => uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp( uniffiClonePointer(), status, ), - FfiConverterUInt64.lift, + FfiConverterMoqTimestamp.lift, null, ); } @@ -16359,6 +16410,53 @@ class FfiConverterOptionalMoqSubscription { } } +class FfiConverterOptionalMoqTimestamp { + static MoqTimestamp? lift(RustBuffer buf) { + return FfiConverterOptionalMoqTimestamp.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + if (ByteData.view(buf.buffer, buf.offsetInBytes).getInt8(0) == 0) { + return LiftRetVal(null, 1); + } + final result = FfiConverterMoqTimestamp.read( + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ); + return LiftRetVal(result.value, result.bytesRead + 1); + } + + static int allocationSize([MoqTimestamp? value]) { + if (value == null) { + return 1; + } + return FfiConverterMoqTimestamp.allocationSize(value) + 1; + } + + static RustBuffer lower(MoqTimestamp? value) { + if (value == null) { + return toRustBuffer(Uint8List.fromList([0])); + } + final buf = Uint8List( + FfiConverterOptionalMoqTimestamp.allocationSize(value), + ); + FfiConverterOptionalMoqTimestamp.write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqTimestamp? value, Uint8List buf) { + if (value == null) { + buf[0] = 0; + return 1; + } + buf[0] = 1; + return FfiConverterMoqTimestamp.write( + value, + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ) + + 1; + } +} + class FfiConverterOptionalMoqTokens { static MoqTokens? lift(RustBuffer buf) { return FfiConverterOptionalMoqTokens.read(buf.asUint8List()).value; @@ -18001,7 +18099,7 @@ external void uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_finish( external void uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( Pointer ptr, RustBuffer value, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18073,7 +18171,7 @@ external Pointer uniffi_moq_ffi_fn_constructor_moqjsonstreamproducer_new( external void uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( Pointer ptr, RustBuffer value, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18185,7 +18283,7 @@ external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_finish( external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( Pointer ptr, int count, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18195,7 +18293,7 @@ external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_push( Pointer ptr, RustBuffer value, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18267,10 +18365,10 @@ external void uniffi_moq_ffi_fn_method_moqmediacatalogproducer_finish( Pointer uniffiStatus, ); -@Native, Pointer)>( +@Native, Pointer)>( assetId: _uniffiAssetId, ) -external int uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( +external RustBuffer uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( Pointer ptr, Pointer uniffiStatus, ); @@ -19796,10 +19894,10 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqvideodecodedframe_surface( Pointer uniffiStatus, ); -@Native, Pointer)>( +@Native, Pointer)>( assetId: _uniffiAssetId, ) -external int uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp_us( +external RustBuffer uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp( Pointer ptr, Pointer uniffiStatus, ); @@ -20880,7 +20978,7 @@ external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_pixels(); external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_surface(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp_us(); +external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_width(); @@ -21179,7 +21277,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() != - 17590) { + 41112) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_cancel() != 29308) { @@ -21188,7 +21286,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_next() != 21257) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 36078) { + if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 57310) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_demand() != 52854) { @@ -21212,10 +21310,10 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_finish() != 49018) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 62669) { + if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 58245) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 19295) { + if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 47237) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_cancel() != @@ -21229,7 +21327,7 @@ void _checkApiChecksums() { 62353) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_now() != 14140) { + if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_now() != 17945) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_remove_section() != @@ -21437,7 +21535,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqgroupproducer_sequence() != 21067) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqgroupproducer_write_frame() != 42053) { + if (uniffi_moq_ffi_checksum_method_moqgroupproducer_write_frame() != 38774) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackproducer_abort() != 37537) { @@ -21475,7 +21573,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqtrackproducer_requests() != 60252) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackproducer_write_frame() != 32196) { + if (uniffi_moq_ffi_checksum_method_moqtrackproducer_write_frame() != 46891) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackrequest_abort() != 62713) { @@ -21600,8 +21698,8 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_surface() != 3872) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp_us() != - 18681) { + if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp() != + 47810) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_width() != 30916) { diff --git a/dart/moq_ffi/test/leak_test.dart b/dart/moq_ffi/test/leak_test.dart index bbbb3ccd1d0..b415f69aa23 100644 --- a/dart/moq_ffi/test/leak_test.dart +++ b/dart/moq_ffi/test/leak_test.dart @@ -85,7 +85,12 @@ void main() { ); final consumer = track.consume(subscription: null); final producer = track.appendGroup(); - producer.writeFrame(frame: MoqFrame(payload: payload, timestampUs: 0)); + producer.writeFrame( + frame: MoqFrame( + payload: payload, + timestamp: MoqTimestamp(value: 0, scale: 1000000), + ), + ); producer.finish(); final group = await consumer.nextGroup(); final frame = await group!.readFrame(); diff --git a/dart/moq_ffi/test/smoke_test.dart b/dart/moq_ffi/test/smoke_test.dart index d7aec01bc79..ad52d65f94f 100644 --- a/dart/moq_ffi/test/smoke_test.dart +++ b/dart/moq_ffi/test/smoke_test.dart @@ -54,7 +54,10 @@ void main() { final producer = track.appendGroup(); producer.writeFrame( - frame: MoqFrame(payload: utf8.encode('dart'), timestampUs: 0), + frame: MoqFrame( + payload: utf8.encode('dart'), + timestamp: MoqTimestamp(value: 0, scale: 1000000), + ), ); producer.finish(); diff --git a/demo/carla/sim/moq_carla_sim/bridge.py b/demo/carla/sim/moq_carla_sim/bridge.py index 98b8aa5c7aa..b49411c490d 100644 --- a/demo/carla/sim/moq_carla_sim/bridge.py +++ b/demo/carla/sim/moq_carla_sim/bridge.py @@ -16,7 +16,6 @@ import logging import struct from dataclasses import dataclass -from datetime import timedelta from typing import Callable import moq @@ -371,7 +370,7 @@ def publish(self, frame: Frame) -> None: raise BridgeError(f"{self.name}: frame before config for rendition {frame.rendition}") if self._origin_us is None: self._origin_us = frame.timestamp_us - timestamp = timedelta(microseconds=max(0, frame.timestamp_us - self._origin_us)) + timestamp = moq.Timestamp(max(0, frame.timestamp_us - self._origin_us), 1_000_000) track.write_frame(frame.payload, timestamp) self.published[frame.rendition] += 1 diff --git a/demo/carla/sim/tests/conftest.py b/demo/carla/sim/tests/conftest.py index 2c0dd55e273..db43ae77ac6 100644 --- a/demo/carla/sim/tests/conftest.py +++ b/demo/carla/sim/tests/conftest.py @@ -67,6 +67,7 @@ async def __aiter__(self): moq.AnnounceEventRestart = AnnounceEventRestart moq.AnnounceRoute = lambda **kwargs: SimpleNamespace(**kwargs) moq.mint_epoch = lambda: str(uuid.uuid4()) +moq.Timestamp = lambda value, scale: SimpleNamespace(value=value, scale=scale) moq.TrackInfo = lambda **kwargs: SimpleNamespace(**kwargs) moq_json = ModuleType("moq.json") diff --git a/demo/carla/sim/tests/test_bridge.py b/demo/carla/sim/tests/test_bridge.py index 628f307751a..1a60d4dd17c 100644 --- a/demo/carla/sim/tests/test_bridge.py +++ b/demo/carla/sim/tests/test_bridge.py @@ -1,6 +1,5 @@ import asyncio import struct -from datetime import timedelta from types import SimpleNamespace import moq @@ -117,10 +116,6 @@ async def wanted_changed(self) -> int | None: return self._wanted -def microseconds(timestamp: timedelta) -> int: - return timestamp // timedelta(microseconds=1) - - class FakeTrack: def __init__(self, init: bytes, name: str, hint) -> None: self.init = init @@ -133,8 +128,9 @@ def __init__(self, init: bytes, name: str, hint) -> None: def demand(self) -> FakeDemand: return self.demand_handle - def write_frame(self, payload: bytes, timestamp: timedelta) -> None: - self.frames.append((payload, microseconds(timestamp))) + def write_frame(self, payload: bytes, timestamp: SimpleNamespace) -> None: + assert timestamp.scale == 1_000_000 + self.frames.append((payload, timestamp.value)) def finish(self) -> None: self.finished = True diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 7ff1a06b29d..be8e7e1d4c9 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -106,7 +106,8 @@ inside. The header is the reference: each function carries a doc comment. - **Catalog hints.** Give the catalog what the encoder knows instead of having it estimated: `moq_video_init.hint` (coded size, bitrate, frame rate, group duration) and `moq_audio_init.hint` (bitrate, group duration). A supplied bitrate is never re-estimated. `group_duration_us` is the longest span between two group starts: the GOP, or your cut cadence. Leave a field's `has_*` flag false to have it measured. A bitrate or `group_duration_us` flag set with a 0 value returns `MOQ_ERROR_INVALID_CONFIG`. - **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE`, which readers take as the publisher leaving, and its handle is released. - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. -- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's `timestamp_us`, rounded down to a whole microsecond; `timestamp_present` is false on an untimed track. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. +- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. JSON and binary writes take one too, converted to their track's milliseconds; NULL stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index e18071c50c1..a1f585d6871 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -122,6 +122,9 @@ use one source timeline; omitting it keeps an independent offset. A timebase bel its broadcast and does not keep it open. `MediaContainerProducer` takes chunks split anywhere, so a raw byte stream needs no other importer. `moq::ContainerFormat::kFmp4` splits each fragment into one frame per sample. +Media times are exact `moq::Timestamp{value, scale}` records, `value` units at `scale` units +per second, and read back at the track's timescale, so a 90 kHz tick republishes unchanged. +A raw `moq::Frame` with `std::nullopt` is untimed. ```cpp // Publish encoded frames, or raw pixels with the codec inside the binding. @@ -130,12 +133,12 @@ anywhere, so a raw byte stream needs no other importer. auto publication = ok(session->publish()->create_broadcast("my-stream.hang")); auto broadcast = publication->broadcast(); // fill tracks here; announce on the publication auto audio = ok(moq::MediaTrackProducer::audio(broadcast, moq::MediaTarget::kNamed{}, {moq::AudioFormat::kOpus, opus_init})); -ok(audio->write_frame({packet, 20'000})); +ok(audio->write_frame({packet, moq::Timestamp{960, 48'000}})); // 20 ms moq::VideoEncoderOutput output{moq::VideoCodec::kH264, std::nullopt, std::nullopt, moq::VideoEncoderKind::kAuto{}}; auto catalog = ok(moq::MediaCatalogProducer::init(broadcast)); auto video = ok(moq::VideoProducer::init(catalog, {{moq::VideoPixelFormat::kRgba, 1280, 720, {30000, 1001}}, output, "camera", nullptr})); -ok(video->write({0, rgba})); +ok(video->write({{0, 30'000}, rgba})); moq::AnnounceRoute route; route.epoch = moq::mint_epoch(); // a fresh epoch per run ok(publication->announce(route)); diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index c0e8137e9f3..3a8341a1fb8 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -19,8 +19,10 @@ and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns cata and sections; it holds the broadcast weakly and fails after the broadcast closes. Publish JSON tracks with `MoqTrackInfo(compress: true)`; a `package:moq/json.dart` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. -`package:moq/json.dart` consumers return `Value` (`value`, `timestampUs`) from `next()`; a snapshot consumer -yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. +`package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer +yields each state in order, and `latest()` skips to the newest. +Media times are exact `Timestamp` records, `value` units at `scale` units per second, so a 90 kHz tick survives a +read and republish. `Duration.toTimestamp()` converts exactly; `Timestamp.toDuration()` rounds down to a whole microsecond. Raw tracks with a `null` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Whole-frame media writes require caller time; container imports keep their own timeline handling. @@ -95,7 +97,7 @@ final encoder = video.Producer( track: 'camera', ), ); -encoder.write(frame: video.Frame(timestampUs: pts, data: rgba)); +encoder.write(frame: video.Frame(timestamp: pts, data: rgba)); camera.announce(route: AnnounceRoute(epoch: mintEpoch())); encoder.finish(); ``` @@ -127,7 +129,7 @@ final publication = moq.createBroadcast('live/camera'); final mine = publication.broadcast(); final track = mine.publishTrack(name: 'video', info: null); final group = track.appendGroup(); -group.writeFrame(frame: Frame(payload: bytes, timestampUs: null)); +group.writeFrame(frame: Frame(payload: bytes, timestamp: null)); group.finish(); publication.announce(route: AnnounceRoute(epoch: mintEpoch())); // a fresh epoch per run track.finish(); diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index abbd367e135..9b33db5e99f 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -16,13 +16,15 @@ linux/amd64, linux/arm64, darwin/arm64 (macOS 12.3+), windows/amd64. `moq.dev/moq/media` owns catalogs, encoded imports, and container consumers. Construct `NewAudioTrackProducer` / `NewVideoTrackProducer` from a broadcast, an init record, and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast weakly; -catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps use `time.Duration`. +catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps are exact +`moq.Timestamp` records (`Value` at `Scale` units per second), so a 90 kHz tick survives a read and republish; +`TimestampFromDuration` converts exactly; `TimestampToDuration` rounds down to a whole nanosecond. A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. `TrackInfo.Compress` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. -The JSON producers' `Update` / `Append` take a final `*time.Duration` timestamp argument (`nil` for untimed). +The JSON producers' `Update` / `Append` take a final `*moq.Timestamp` argument (`nil` for untimed). JSON consumers return a `*Timed` holding the value and that timestamp; `SnapshotConsumer.Latest` -skips to the newest state where `Next` yields each one. Read timestamps are rounded down to a whole microsecond. +skips to the newest state where `Next` yields each one. A read timestamp is at the track's timescale. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.Now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. @@ -91,16 +93,15 @@ for event, err := range announced.All(ctx) { ```go import ( - "time" moqvideo "moq.dev/moq/video" ) // Publish encoded frames, or raw pixels with the codec inside the binding. -// opusInit, packet, pts, and rgba come from your encoder or capture source. +// opusInit, packet, pts (90 kHz ticks), and rgba come from your encoder or capture source. publication, _ := client.CreateBroadcast("my-stream.hang") broadcast := publication.Broadcast() audio, _ := moqmedia.NewAudioTrackProducer(broadcast, moqmedia.Named{}, moqmedia.AudioInit{Format: moqmedia.AudioFormatOpus, Data: opusInit}) -timestamp := 20 * time.Millisecond +timestamp := moq.Timestamp{Value: 960, Scale: 48_000} // 20 ms on the Opus sample clock _ = audio.WriteFrame(moq.Frame{Payload: packet, Timestamp: ×tamp}) _ = audio.Cut() // audio has no keyframes, so this is what gives it groups @@ -111,7 +112,7 @@ video, _ := moqvideo.NewProducer(catalogProducer, moqvideo.ProducerOptions{ Output: moqvideo.EncoderOutput{Codec: moq.VideoCodecH264, Kind: moq.AutoEncoder()}, Track: &track, }) -_ = video.Write(moqvideo.Frame{Timestamp: time.Duration(pts) * time.Microsecond, Data: rgba}) +_ = video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: pts, Scale: 90_000}, Data: rgba}) epoch := moq.MintEpoch() // a fresh epoch per run _ = publication.Announce(moq.AnnounceRoute{Epoch: &epoch}) _ = audio.Finish() diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index f4c5271ea27..579f49b0c47 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -19,7 +19,9 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). Publish JSON tracks with `TrackInfo(compress = true)`; a `dev.moq.json` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; -a snapshot consumer yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. +a snapshot consumer yields each state in order, and `latest()` skips to the newest. +A `Timestamp(value, scale)` is exact and reads back at the track's timescale, so a 90 kHz tick republishes unchanged. +`Duration.toTimestamp()` is exact at nanosecond scale; `Timestamp.toDuration()` rounds down to a whole nanosecond. Raw tracks with a `null` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Whole-frame media writes require caller time; container imports keep their own timeline handling. @@ -74,7 +76,7 @@ Moq.connect("https://relay.example.com").use { moq -> val publication = moq.createBroadcast("my-stream.hang") val broadcast = publication.broadcast() val audio = dev.moq.media.TrackProducer.audio(broadcast, Named(null), AudioInit(format = AudioFormat.OPUS, data = opusInit)) - audio.writeFrame(Frame(payload = packet, timestampUs = 20_000u)) + audio.writeFrame(Frame(payload = packet, timestamp = Timestamp(960u, 48_000u))) audio.cut() // audio has no keyframes, so this is what gives it groups val video = dev.moq.video.Producer( @@ -82,7 +84,7 @@ Moq.connect("https://relay.example.com").use { moq -> dev.moq.video.ProducerOptions(input = VideoEncoderInput(format = VideoPixelFormat.RGBA, width = 1280u, height = 720u, framerate = dev.moq.video.FrameRate(30000u, 1001u)), output = VideoEncoderOutput(codec = VideoCodec.H264, bitrate = null, gop = null, kind = autoEncoder), track = "camera"), ) - video.write(VideoFrame(timestampUs = pts, data = rgba)) + video.write(VideoFrame(timestamp = pts, data = rgba)) publication.announce(AnnounceRoute(epoch = mintEpoch())) // a fresh epoch per run audio.finish() video.finish() diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index f6aead8f1ce..64235560695 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -22,13 +22,14 @@ source timeline; omitting it keeps an independent offset. A timebase belongs to broadcast and does not keep it open. `ContainerProducer` takes chunks split anywhere, so a raw byte stream needs no other importer. `ContainerFormat.FMP4` splits each fragment into one frame per sample. -`MediaFrame.timestamp`, media writes, and `flush` use `datetime.timedelta`. +Media timestamps are exact `moq.Timestamp(value, scale)` records, so a 90 kHz tick survives a read and republish. +`Timestamp.from_timedelta` is exact; `.to_timedelta()` rounds down to a whole microsecond. A missing data timestamp stays untimed; the library never substitutes zero or now. JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yields each state in order, -and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Read timestamps are rounded down to a whole microsecond. +and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Raw tracks with a `None` timescale are untimed on both publish and receive. `TrackInfo(compress=True)` sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Set it on JSON tracks. -The JSON producers' `update` / `append` accept `timestamp=timedelta(...)` (`None` for untimed). +The JSON producers' `update` / `append` accept `timestamp=moq.Timestamp(...)` (`None` for untimed). Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index cb7d732b8e5..454ea1e9772 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -17,10 +17,13 @@ slices for iOS 16+, the iOS Simulator, and macOS 12.3+. `.named(name:)` or `.requested(request)` target. `Media.CatalogProducer(broadcast:)` updates catalog properties and sections without keeping the broadcast open. Its writes fail after closing or releasing the broadcast. +Media timestamps are exact `Timestamp` records, `value` units at `scale` units per second, carried at the track's timescale +(a write at another scale rounds down to it). On macOS 13+ and iOS, `try Timestamp(duration)` converts a `Duration` exactly, +and `try timestamp.duration` rounds down to a whole attosecond. Publish JSON tracks with `TrackInfo(compress: true)`; a `Json` consumer reads one with no option of its own. A missing data timestamp stays untimed; the library never substitutes zero or now. -`Json` consumers yield `Json.Timed` (`value`, `timestampUs`); a snapshot consumer yields each state in order, -and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. +`Json` consumers yield `Json.Timed` (`value`, `timestamp`); a snapshot consumer yields each state in order, +and `latest()` skips to the newest. Raw tracks with a `nil` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. Whole-frame media writes require caller time; container imports keep their own timeline handling. @@ -73,7 +76,7 @@ for try await event in try session.consume.announced(prefix: "live/", filter: "* let publication = try session.publish.createBroadcast(path: "my-stream.hang") let broadcast = publication.broadcast let audio = try Media.TrackProducer.audio(broadcast: broadcast, initData: Media.AudioInit(format: .opus, data: opusInit)) -try audio.writeFrame(packet, timestampUs: 20_000) +try audio.writeFrame(packet, timestamp: Timestamp(value: 20, scale: 1_000)) try audio.cut() // audio has no keyframes, so this is what gives it groups let video = try Video.Producer( @@ -82,7 +85,7 @@ let video = try Video.Producer( output: VideoEncoderOutput(codec: .h264, kind: .auto), track: "camera" ) -try video.write(VideoFrame(timestampUs: pts, data: rgba)) +try video.write(VideoFrame(timestamp: pts, data: rgba)) try publication.announce(route: AnnounceRoute(epoch: mintEpoch())) // a fresh epoch per run try audio.finish() try video.finish() diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 42bfdb5079e..dc8f4550fba 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -99,7 +99,7 @@ catalog snapshots, live media, and one fetched media group. The last two take a (`VideoRendition` or `AudioRendition`: a catalog ID and its config) and follow its broadcast and track themselves. `NewGroupConsumer` decodes a raw group, such as one from `moq.TrackConsumer.RecvGroup` for arrival-order reads. -Frames and `Flush` use `time.Duration`; `Demand()` owns track names and subscriber waits. +Frames carry exact `moq.Timestamp` records; `Demand()` owns track names and subscriber waits. `BroadcastProducer.Requests()` accepts subscriber-requested tracks. Call `TrackRequest.Accept()` for raw tracks, or pass the request as `media.Requested` @@ -114,7 +114,7 @@ carry every record in order. `NewWindowProducer` / `NewWindowConsumer` carry a s of records a reader can join at any point; the catalog has no window mode, so the producer takes only the track. Producers accept any `encoding/json` value; consumers return `json.RawMessage` so callers choose their own decoded type. -`Update` / `Append` / `Push` / `Pop` take a final `*time.Duration` on the broadcast clock; nil publishes untimed. +`Update` / `Append` / `Push` / `Pop` take a final `*moq.Timestamp` on the broadcast clock; nil publishes untimed. Raw tracks with a nil timescale are untimed; timed tracks require matching timestamps. `media.CatalogProducer.Now()` samples and fixes the catalog clock for explicit local-event stamps. Opaque bytes go on a plain `TrackProducer`. diff --git a/go/wrapper/audio/audio.go b/go/wrapper/audio/audio.go index 432ff028329..1ccf0c68989 100644 --- a/go/wrapper/audio/audio.go +++ b/go/wrapper/audio/audio.go @@ -88,19 +88,7 @@ func delay(d *media.Delay, kind string) error { } // Frame is interleaved PCM with its presentation timestamp. -type Frame struct { - Timestamp time.Duration - Data []byte -} - -func (f Frame) ffi() (ffi.MoqAudioFrame, error) { - us, err := bridge.Duration(f.Timestamp, "audio timestamp") - return ffi.MoqAudioFrame{TimestampUs: us, Data: f.Data}, err -} - -func frame(raw ffi.MoqAudioFrame) Frame { - return Frame{Timestamp: time.Duration(raw.TimestampUs) * time.Microsecond, Data: raw.Data} -} +type Frame = ffi.MoqAudioFrame // Read is one item a Consumer reads, in delivery order: a ReadFrame, ReadGap, or ReadEnd. type Read interface{ read() } @@ -113,7 +101,7 @@ type ReadFrame struct { // ReadGap is media lost after what was already read: what follows does not continue it. type ReadGap struct { // Timestamp is the furthest presentation point already read. - Timestamp time.Duration + Timestamp moq.Timestamp // Duration is an upper bound on how long until the next frame resumes. Duration time.Duration } @@ -123,7 +111,7 @@ type ReadGap struct { // comes from a fresh encoder. type ReadEnd struct { // End is where the stopped encoder's media stops. - End time.Duration + End moq.Timestamp } func (ReadFrame) read() {} @@ -133,11 +121,11 @@ func (ReadEnd) read() {} func audioRead(raw ffi.MoqAudioRead) (Read, error) { switch read := raw.(type) { case ffi.MoqAudioReadFrame: - return ReadFrame{Frame: frame(read.Frame)}, nil + return ReadFrame{Frame: read.Frame}, nil case ffi.MoqAudioReadGap: - return ReadGap{Timestamp: time.Duration(read.TimestampUs) * time.Microsecond, Duration: read.Duration}, nil + return ReadGap{Timestamp: read.Timestamp, Duration: read.Duration}, nil case ffi.MoqAudioReadEnd: - return ReadEnd{End: time.Duration(read.EndUs) * time.Microsecond}, nil + return ReadEnd{End: read.End}, nil } return nil, fmt.Errorf("unknown audio read: %T", raw) } @@ -189,11 +177,7 @@ func (p *Producer) Reanchor() error { return p.inner.Reanchor() } // Write encodes and publishes one PCM frame in the configured input layout. func (p *Producer) Write(value Frame) error { - raw, err := value.ffi() - if err != nil { - return err - } - return p.inner.Write(raw) + return p.inner.Write(value) } // Reservation returns this track's bandwidth reservation, or nil without one. diff --git a/go/wrapper/bridge.go b/go/wrapper/bridge.go index 116ac0f1392..3209b931ca7 100644 --- a/go/wrapper/bridge.go +++ b/go/wrapper/bridge.go @@ -10,7 +10,6 @@ import ( func init() { bridge.BroadcastConsumer = func(v any) *ffi.MoqBroadcastConsumer { return v.(*BroadcastConsumer).inner } bridge.TrackRequest = func(v any) *ffi.MoqTrackRequest { return v.(*TrackRequest).inner } - bridge.Frame = func(v any) (ffi.MoqFrame, error) { return v.(Frame).ffi() } bridge.Subscription = func(v any) (*ffi.MoqSubscription, error) { return subscriptionFFI(v.(*Subscription)) } bridge.BroadcastProducer = func(v any) *ffi.MoqBroadcastProducer { return v.(*BroadcastProducer).inner } diff --git a/go/wrapper/data_timestamps_test.go b/go/wrapper/data_timestamps_test.go index 054ab009672..ea45972d2d5 100644 --- a/go/wrapper/data_timestamps_test.go +++ b/go/wrapper/data_timestamps_test.go @@ -3,21 +3,35 @@ package moq_test import ( "context" "encoding/json" + "errors" "testing" - "time" "moq.dev/moq" moqjson "moq.dev/moq/json" ) +// A 90 kHz tick has no exact microsecond count, so it survives only as a record. +var tick = moq.Timestamp{Value: 1, Scale: 90_000} + +func ninetyKHz() *moq.TrackInfo { + scale := uint64(90_000) + return &moq.TrackInfo{Timescale: &scale} +} + +// Every producer carries an exact timestamp, a present zero, or none at all, and +// the raw reader gets back exactly what was written. func TestDataTimestamps(t *testing.T) { - for _, mode := range []string{"json snapshot", "json stream"} { - for _, timed := range []bool{false, true} { - name := mode + "/untimed" - if timed { - name = mode + "/timed" - } - t.Run(name, func(t *testing.T) { + timestamps := []struct { + name string + at *moq.Timestamp + }{ + {"untimed", nil}, + {"zero", &moq.Timestamp{Value: 0, Scale: 90_000}}, + {"tick", &tick}, + } + for _, mode := range []string{"frame", "json snapshot", "json stream"} { + for _, timestamp := range timestamps { + t.Run(mode+"/"+timestamp.name, func(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() broadcast, err := moq.NewBroadcastProducer() @@ -25,12 +39,9 @@ func TestDataTimestamps(t *testing.T) { t.Fatal(err) } defer broadcast.Close() - var timestamp *time.Duration var info *moq.TrackInfo - if timed { - at := 123456 * time.Microsecond - timestamp = &at - info = timedInfo() + if timestamp.at != nil { + info = ninetyKHz() } track, err := broadcast.PublishTrack("data", info) if err != nil { @@ -41,31 +52,9 @@ func TestDataTimestamps(t *testing.T) { t.Fatal(err) } defer consumer.Cancel() - switch mode { - case "json snapshot": - producer, err := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{}) - if err != nil { - t.Fatal(err) - } - err = producer.Update(map[string]int{"n": 1}, timestamp) - if err != nil { - t.Fatal(err) - } - if err := producer.Finish(); err != nil { - t.Fatal(err) - } - case "json stream": - producer, err := moqjson.NewStreamProducer(broadcast, track) - if err != nil { - t.Fatal(err) - } - err = producer.Append(map[string]int{"n": 1}, timestamp) - if err != nil { - t.Fatal(err) - } - if err := producer.Finish(); err != nil { - t.Fatal(err) - } + payload := []byte("opaque payload") + if err := publishData(mode, broadcast, track, payload, timestamp.at); err != nil { + t.Fatal(err) } frame, err := consumer.ReadFrame(ctx) if err != nil { @@ -74,15 +63,77 @@ func TestDataTimestamps(t *testing.T) { if frame == nil { t.Fatal("missing frame") } - if (frame.Timestamp == nil) != (timestamp == nil) || timestamp != nil && *frame.Timestamp != *timestamp { - t.Fatalf("timestamp = %v, want %v", frame.Timestamp, timestamp) + want := timestamp.at + if (frame.Timestamp == nil) != (want == nil) || want != nil && *frame.Timestamp != *want { + t.Fatalf("timestamp = %+v, want %+v", frame.Timestamp, want) } - var value map[string]int - if err := json.Unmarshal(frame.Payload, &value); err != nil { + if mode == "json snapshot" || mode == "json stream" { + var value map[string]int + if err := json.Unmarshal(frame.Payload, &value); err != nil { + t.Fatal(err) + } + if value["n"] != 1 { + t.Fatalf("payload = %s", frame.Payload) + } + } else if string(frame.Payload) != string(payload) { + t.Fatalf("payload = %q", frame.Payload) + } + }) + } + } +} + +// publishData writes one value at timestamp through the producer mode names, then finishes. +func publishData(mode string, broadcast *moq.BroadcastProducer, track *moq.TrackProducer, payload []byte, timestamp *moq.Timestamp) error { + switch mode { + case "frame": + return track.WriteFrame(moq.Frame{Payload: payload, Timestamp: timestamp}) + case "json snapshot": + producer, err := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{}) + if err != nil { + return err + } + if err := producer.Update(map[string]int{"n": 1}, timestamp); err != nil { + return err + } + return producer.Finish() + case "json stream": + producer, err := moqjson.NewStreamProducer(broadcast, track) + if err != nil { + return err + } + if err := producer.Append(map[string]int{"n": 1}, timestamp); err != nil { + return err + } + return producer.Finish() + } + panic("unknown mode " + mode) +} + +// A zero scale, or a value or scale past what the wire carries, is refused rather +// than clamped, from a raw frame and a data producer alike. +func TestTimestampRefused(t *testing.T) { + for _, bad := range []struct { + name string + at moq.Timestamp + }{ + {"zero scale", moq.Timestamp{Value: 1, Scale: 0}}, + {"scale 2^62", moq.Timestamp{Value: 1, Scale: 1 << 62}}, + {"value 2^61", moq.Timestamp{Value: 1 << 61, Scale: 90_000}}, + } { + for _, mode := range []string{"frame", "json stream"} { + t.Run(mode+"/"+bad.name, func(t *testing.T) { + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + defer broadcast.Close() + track, err := broadcast.PublishTrack("data", ninetyKHz()) + if err != nil { t.Fatal(err) } - if value["n"] != 1 { - t.Fatalf("payload = %s", frame.Payload) + if err := publishData(mode, broadcast, track, []byte("x"), &bad.at); !errors.Is(err, moq.ErrTimeOverflow) { + t.Fatalf("err = %v, want ErrTimeOverflow", err) } }) } diff --git a/go/wrapper/doc.go b/go/wrapper/doc.go index 336714fb0db..e4dba0028ac 100644 --- a/go/wrapper/doc.go +++ b/go/wrapper/doc.go @@ -5,7 +5,7 @@ // idiomatic Go: context.Context cancellation, Go error returns, and Go 1.23 // range-over-func iterators (iter.Seq2) for live streams. The raw record, // enum, and small object types are re-exported here without the Moq prefix (see types.go), -// records with timestamps carry time.Duration (see records.go), so +// media timestamps are exact Timestamp records (see records.go), so // most programs never need to import the ffi package directly. // // A typical full-duplex client wires a single origin as both publish source diff --git a/go/wrapper/errors.go b/go/wrapper/errors.go index f873990bcb4..92606424e51 100644 --- a/go/wrapper/errors.go +++ b/go/wrapper/errors.go @@ -41,7 +41,7 @@ var ( ErrVideo = ffi.ErrMoqErrorVideo // ErrURL matches a malformed URL passed when connecting or publishing. ErrURL = ffi.ErrMoqErrorUrl - // ErrTimeOverflow matches a timestamp outside the supported range. + // ErrTimeOverflow matches a timestamp value or scale outside the supported range, or a zero scale. ErrTimeOverflow = ffi.ErrMoqErrorTimeOverflow // ErrLogLevel matches an unparseable log level string passed to LogLevel. ErrLogLevel = ffi.ErrMoqErrorLogLevel diff --git a/go/wrapper/example_test.go b/go/wrapper/example_test.go index 88e6494ea15..da49aff1e08 100644 --- a/go/wrapper/example_test.go +++ b/go/wrapper/example_test.go @@ -4,7 +4,6 @@ import ( "context" "fmt" "log" - "time" "moq.dev/moq" moqmedia "moq.dev/moq/media" @@ -62,7 +61,8 @@ func ExampleClient_CreateBroadcast() { } _ = publication.Announce(moq.AnnounceRoute{}) - pts := 20 * time.Millisecond + // 20 ms in, counted on the Opus 48 kHz sample clock. + pts := moq.Timestamp{Value: 960, Scale: 48_000} if err := media.WriteFrame(moq.Frame{Payload: []byte("opus frame"), Timestamp: &pts}); err != nil { log.Fatal(err) } diff --git a/go/wrapper/internal/bridge/handles.go b/go/wrapper/internal/bridge/handles.go index 39dc92d85e8..1ed1fbdfeed 100644 --- a/go/wrapper/internal/bridge/handles.go +++ b/go/wrapper/internal/bridge/handles.go @@ -38,21 +38,9 @@ var BroadcastConsumer func(any) *ffi.MoqBroadcastConsumer // TrackRequest returns the handle behind a *moq.TrackRequest. var TrackRequest func(any) *ffi.MoqTrackRequest -// Frame converts a moq.Frame to the generated record. -var Frame func(any) (ffi.MoqFrame, error) - // Subscription converts a *moq.Subscription to the generated record. var Subscription func(any) (*ffi.MoqSubscription, error) -// Duration converts d to microseconds, refusing a negative duration rather -// than letting it wrap when cast to uint64. -func Duration(d time.Duration, name string) (uint64, error) { - if d < 0 { - return 0, fmt.Errorf("negative %s: %v", name, d) - } - return uint64(d.Microseconds()), nil -} - // NonNegative refuses a negative duration, which the generated converter // would panic on rather than return an error. func NonNegative(value *time.Duration, name string) error { @@ -69,15 +57,3 @@ func Rendition(rendition ffi.MoqRendition) error { } return nil } - -// OptionalDuration converts a caller's time to microseconds, preserving absence. -func OptionalDuration(value *time.Duration, name string) (*uint64, error) { - if value == nil { - return nil, nil - } - us, err := Duration(*value, name) - if err != nil { - return nil, err - } - return &us, nil -} diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 3406efdd7f5..138f045919e 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -16,7 +16,6 @@ import ( stdjson "encoding/json" "fmt" "iter" - "time" "moq.dev/moq" ffi "moq.dev/moq-ffi/moq" @@ -70,16 +69,12 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu // Update publishes value at timestamp on the broadcast clock; nil is untimed. // It is a no-op when unchanged. -func (p *SnapshotProducer) Update(value any, timestamp *time.Duration) error { +func (p *SnapshotProducer) Update(value any, timestamp *moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Update(string(encoded), at) + return p.inner.Update(string(encoded), timestamp) } // Demand returns a watch-only handle to whether the track has subscribers. @@ -113,16 +108,12 @@ func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProduce } // Append adds one JSON record at timestamp on the broadcast clock; nil is untimed. -func (p *StreamProducer) Append(value any, timestamp *time.Duration) error { +func (p *StreamProducer) Append(value any, timestamp *moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Append(string(encoded), at) + return p.inner.Append(string(encoded), timestamp) } // Demand returns a watch-only handle to whether the track has subscribers. @@ -143,22 +134,15 @@ func (p *StreamProducer) Finish() error { type Timed struct { // Value is the JSON document. Value stdjson.RawMessage - // Timestamp is on the broadcast clock, or nil on an untimed track. It is rounded down - // to a whole microsecond, so a tick on a track like 90 kHz may not survive a read and - // republish exactly. - Timestamp *time.Duration + // Timestamp is on the broadcast clock, or nil on an untimed track. + Timestamp *moq.Timestamp } func timed(value *ffi.MoqJsonValue) *Timed { if value == nil { return nil } - out := &Timed{Value: stdjson.RawMessage(value.Value)} - if value.TimestampUs != nil { - at := time.Duration(*value.TimestampUs) * time.Microsecond - out.Timestamp = &at - } - return out + return &Timed{Value: stdjson.RawMessage(value.Value), Timestamp: value.Timestamp} } // SnapshotConsumer receives each reconstructed JSON state. @@ -255,26 +239,18 @@ func NewWindowProducer(track *moq.TrackProducer, options WindowOptions) (*Window } // Push appends one JSON record at timestamp on the broadcast clock; nil is untimed. -func (p *WindowProducer) Push(value any, timestamp *time.Duration) error { +func (p *WindowProducer) Push(value any, timestamp *moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Push(string(encoded), at) + return p.inner.Push(string(encoded), timestamp) } // Pop drops count records from the front of the window, clamped to what it holds, // at timestamp on the broadcast clock; nil is untimed. -func (p *WindowProducer) Pop(count uint64, timestamp *time.Duration) error { - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Pop(count, at) +func (p *WindowProducer) Pop(count uint64, timestamp *moq.Timestamp) error { + return p.inner.Pop(count, timestamp) } // Cut closes the open group, so the next edit opens one restating the retained @@ -340,14 +316,14 @@ type TimedWindowEvent struct { // Timestamp is on the broadcast clock, or nil on an untimed track. A record // first learned of from a group's restatement carries that frame's time, not // its original push time. - Timestamp *time.Duration + Timestamp *moq.Timestamp } func timedWindowEvent(value *ffi.MoqJsonWindowTimed) (*TimedWindowEvent, error) { if value == nil { return nil, nil } - out := &TimedWindowEvent{} + out := &TimedWindowEvent{Timestamp: value.Timestamp} switch event := value.Event.(type) { case ffi.MoqJsonWindowEventPush: out.Event = WindowPush{Index: event.Index, Value: stdjson.RawMessage(event.Value)} @@ -358,10 +334,6 @@ func timedWindowEvent(value *ffi.MoqJsonWindowTimed) (*TimedWindowEvent, error) default: return nil, fmt.Errorf("unknown window event: %T", event) } - if value.TimestampUs != nil { - at := time.Duration(*value.TimestampUs) * time.Microsecond - out.Timestamp = &at - } return out, nil } diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index d22d13612c6..1cee5ca3a71 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -70,7 +70,7 @@ func TestTracks(t *testing.T) { } defer snapshotConsumer.Cancel() for viewers := 1; viewers <= 4; viewers++ { - at := time.Duration(viewers) * time.Millisecond + at := moq.Timestamp{Value: uint64(viewers) * 1000, Scale: scale} if err := snapshot.Update(map[string]any{"viewers": viewers}, &at); err != nil { t.Fatal(err) } @@ -89,7 +89,7 @@ func TestTracks(t *testing.T) { if decoded["viewers"] != float64(viewers) { t.Fatalf("snapshot = %s, want viewers %d", value.Value, viewers) } - if want := time.Duration(viewers) * time.Millisecond; value.Timestamp == nil || *value.Timestamp != want { + if want := (moq.Timestamp{Value: uint64(viewers) * 1000, Scale: scale}); value.Timestamp == nil || *value.Timestamp != want { t.Fatalf("timestamp = %v, want %v", value.Timestamp, want) } } @@ -149,9 +149,8 @@ func TestWindow(t *testing.T) { } defer windowConsumer.Cancel() - ms := func(n int) *time.Duration { - at := time.Duration(n) * time.Millisecond - return &at + ms := func(n int) *moq.Timestamp { + return &moq.Timestamp{Value: uint64(n) * 1000, Scale: scale} } for n := range 3 { if err := window.Push(map[string]any{"n": n}, ms(n)); err != nil { diff --git a/go/wrapper/media/media.go b/go/wrapper/media/media.go index 2c769bc6860..08a82cd39f1 100644 --- a/go/wrapper/media/media.go +++ b/go/wrapper/media/media.go @@ -91,11 +91,7 @@ type ContainerInit struct { } // MediaFrame is a container-decoded payload, presentation timestamp, and keyframe flag. -type MediaFrame struct { - Payload []byte - Timestamp time.Duration - Keyframe bool -} +type MediaFrame = ffi.MoqMediaFrame // Target is the named or requested track an importer publishes. type Target interface{ target() } @@ -143,9 +139,8 @@ func NewCatalogProducer(broadcast *moq.BroadcastProducer) (*CatalogProducer, err } // Now reads the broadcast clock, fixing it for subsequent media producers. -func (c *CatalogProducer) Now() (time.Duration, error) { - us, err := c.inner.Now() - return time.Duration(us) * time.Microsecond, err +func (c *CatalogProducer) Now() (moq.Timestamp, error) { + return c.inner.Now() } // SetVideoProperties replaces the video properties shared by all renditions. @@ -388,11 +383,7 @@ func (m *TrackProducer) Demand() (*moq.TrackDemand, error) { // WriteFrame appends frame to the media track. The importer derives keyframe status from // the bitstream, so a Frame carries only the payload and its timestamp. func (m *TrackProducer) WriteFrame(frame moq.Frame) error { - f, err := bridge.Frame(frame) - if err != nil { - return err - } - return m.inner.WriteFrame(f) + return m.inner.WriteFrame(frame) } // Discontinuity marks a timeline break, preserving the advertised jitter and delay. @@ -477,14 +468,6 @@ func (m *TrackStreamProducer) Finish() error { return m.inner.Finish() } -// mediaFrame converts the result of a Next call, keeping (nil, nil) for the end. -func mediaFrame(frame *ffi.MoqMediaFrame, err error) (*MediaFrame, error) { - if frame == nil || err != nil { - return nil, err - } - return &MediaFrame{Payload: frame.Payload, Timestamp: time.Duration(frame.TimestampUs) * time.Microsecond, Keyframe: frame.Keyframe}, nil -} - // Read is one encoded frame, a ReadGap, or a ReadEnd, in delivery order. type Read interface{ read() } @@ -493,13 +476,13 @@ type ReadFrame struct{ Frame MediaFrame } // ReadGap is lost media; what follows does not continue it. type ReadGap struct { - Timestamp time.Duration + Timestamp moq.Timestamp Duration time.Duration } // ReadEnd is where a stopped encoder's media stops. Following frames before End // are its remaining media; the first at or past End comes from a fresh encoder. -type ReadEnd struct{ End time.Duration } +type ReadEnd struct{ End moq.Timestamp } func (ReadFrame) read() {} func (ReadGap) read() {} @@ -508,15 +491,11 @@ func (ReadEnd) read() {} func mediaRead(raw ffi.MoqMediaRead) (Read, error) { switch read := raw.(type) { case ffi.MoqMediaReadFrame: - frame, err := mediaFrame(&read.Frame, nil) - if err != nil { - return nil, err - } - return ReadFrame{Frame: *frame}, nil + return ReadFrame{Frame: read.Frame}, nil case ffi.MoqMediaReadGap: - return ReadGap{Timestamp: time.Duration(read.TimestampUs) * time.Microsecond, Duration: read.Duration}, nil + return ReadGap{Timestamp: read.Timestamp, Duration: read.Duration}, nil case ffi.MoqMediaReadEnd: - return ReadEnd{End: time.Duration(read.EndUs) * time.Microsecond}, nil + return ReadEnd{End: read.End}, nil } return nil, fmt.Errorf("unknown media read: %T", raw) } @@ -558,7 +537,7 @@ func (m *GroupConsumer) Sequence() uint64 { // Next returns the next decoded frame, or (nil, nil) when the group ends. func (m *GroupConsumer) Next(ctx context.Context) (*MediaFrame, error) { - return mediaFrame(bridge.Call(ctx, m.inner.Cancel, m.inner.Next)) + return bridge.Call(ctx, m.inner.Cancel, m.inner.Next) } // All ranges over decoded frames until the group ends or the loop breaks. diff --git a/go/wrapper/media/read_test.go b/go/wrapper/media/read_test.go index 1f837a4d5ed..b284cd71e03 100644 --- a/go/wrapper/media/read_test.go +++ b/go/wrapper/media/read_test.go @@ -1,32 +1,35 @@ package media import ( - ffi "moq.dev/moq-ffi/moq" "testing" "time" + + "moq.dev/moq" + ffi "moq.dev/moq-ffi/moq" ) func TestMediaReadPreservesFramesAndBreaks(t *testing.T) { - frame, err := mediaRead(ffi.MoqMediaReadFrame{Frame: ffi.MoqMediaFrame{Payload: []byte("encoded"), TimestampUs: 123456, Keyframe: true}}) + tick := moq.Timestamp{Value: 1, Scale: 90_000} + frame, err := mediaRead(ffi.MoqMediaReadFrame{Frame: ffi.MoqMediaFrame{Payload: []byte("encoded"), Timestamp: tick, Keyframe: true}}) if err != nil { t.Fatal(err) } value, ok := frame.(ReadFrame) - if !ok || string(value.Frame.Payload) != "encoded" || value.Frame.Timestamp != 123456*time.Microsecond || !value.Frame.Keyframe { + if !ok || string(value.Frame.Payload) != "encoded" || value.Frame.Timestamp != tick || !value.Frame.Keyframe { t.Fatalf("frame: %#v", frame) } - gap, err := mediaRead(ffi.MoqMediaReadGap{TimestampUs: 123456, Duration: 78901 * time.Microsecond}) + gap, err := mediaRead(ffi.MoqMediaReadGap{Timestamp: tick, Duration: 78901 * time.Microsecond}) if err != nil { t.Fatal(err) } - if gap != (ReadGap{Timestamp: 123456 * time.Microsecond, Duration: 78901 * time.Microsecond}) { + if gap != (ReadGap{Timestamp: tick, Duration: 78901 * time.Microsecond}) { t.Fatalf("gap: %#v", gap) } - end, err := mediaRead(ffi.MoqMediaReadEnd{EndUs: 202357}) + end, err := mediaRead(ffi.MoqMediaReadEnd{End: tick}) if err != nil { t.Fatal(err) } - if end != (ReadEnd{End: 202357 * time.Microsecond}) { + if end != (ReadEnd{End: tick}) { t.Fatalf("end: %#v", end) } } diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index dd927abf536..39f9bff32ce 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -111,7 +111,7 @@ func TestDynamicBroadcastRequest(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != 0 { + if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != *ts(0) { t.Fatalf("frame = %+v, want payload=%q ts=0", frame, payload) } @@ -136,7 +136,7 @@ func TestPublishAudioLifecycle(t *testing.T) { if err != nil { t.Fatal(err) } - if err := media.WriteFrame(moq.Frame{Payload: []byte("opus frame"), Timestamp: ts(1000 * time.Microsecond)}); err != nil { + if err := media.WriteFrame(moq.Frame{Payload: []byte("opus frame"), Timestamp: ts(1000)}); err != nil { t.Fatal(err) } if err := media.Finish(); err != nil { @@ -226,7 +226,7 @@ func TestEncodeAudioWithOpusObject(t *testing.T) { codec.Destroy() } // One 20 ms Opus frame of silence at 48 kHz mono. - if err := producer.Write(moqaudio.Frame{Data: make([]byte, 960*4)}); err != nil { + if err := producer.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Scale: 48_000}, Data: make([]byte, 960*4)}); err != nil { t.Fatal(err) } if !codecFirst { @@ -311,7 +311,7 @@ func TestAudioConsumerDelay(t *testing.T) { // Two 20 ms Opus frames of silence at 48 kHz mono. for i := range 2 { - if err := audio.Write(moqaudio.Frame{Timestamp: time.Duration(i) * 20 * time.Millisecond, Data: make([]byte, 960*4)}); err != nil { + if err := audio.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Value: uint64(i) * 960, Scale: 48_000}, Data: make([]byte, 960*4)}); err != nil { t.Fatal(err) } } @@ -363,7 +363,7 @@ func TestEncodeAudioFrameDurations(t *testing.T) { t.Fatal(err) } // 2.5 ms of silence at 48 kHz mono f32: exactly one encoded frame. - if err := fine.Write(moqaudio.Frame{Data: make([]byte, 120*4)}); err != nil { + if err := fine.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Scale: 48_000}, Data: make([]byte, 120*4)}); err != nil { t.Fatal(err) } if err := fine.Finish(); err != nil { @@ -450,7 +450,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { t.Fatal(err) } for i := range 10 { - if err := video.Write(moqvideo.Frame{Timestamp: time.Duration(i) * 33333 * time.Microsecond, Data: rgba}); err != nil { + if err := video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: uint64(i) * 1001, Scale: 30_000}, Data: rgba}); err != nil { t.Fatal(err) } } @@ -481,7 +481,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { // Keep the encoder fed so the decoder sees frames after it joined. for i := 10; i < 40; i++ { - if err := video.Write(moqvideo.Frame{Timestamp: time.Duration(i) * 33333 * time.Microsecond, Data: rgba}); err != nil { + if err := video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: uint64(i) * 1001, Scale: 30_000}, Data: rgba}); err != nil { t.Fatal(err) } } @@ -673,7 +673,7 @@ func TestFetchGroupAndServeDynamicMiss(t *testing.T) { if err != nil { t.Fatal(err) } - if err := produced.WriteFrame(moq.Frame{Payload: []byte("archive"), Timestamp: ts(7 * 20_000 * time.Microsecond)}); err != nil { + if err := produced.WriteFrame(moq.Frame{Payload: []byte("archive"), Timestamp: ts(7 * 20_000)}); err != nil { t.Fatal(err) } if err := produced.Finish(); err != nil { @@ -763,7 +763,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { defer mediaConsumer.Cancel() payload := []byte("opus audio payload data") - if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(1_000_000 * time.Microsecond)}); err != nil { + if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(1_000_000)}); err != nil { t.Fatal(err) } @@ -776,7 +776,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { t.Fatalf("expected a media frame, got %T", read) } frame := &value.Frame - if string(frame.Payload) != string(payload) || uint64(frame.Timestamp.Microseconds()) != 1_000_000 { + if string(frame.Payload) != string(payload) || moq.TimestampToDuration(frame.Timestamp) != time.Second { t.Fatalf("frame = %+v, want payload=%q ts=1000000", frame, payload) } @@ -802,7 +802,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != string(payload) || uint64(frame.Timestamp.Microseconds()) != 1_000_000 { + if frame == nil || string(frame.Payload) != string(payload) || moq.TimestampToDuration(frame.Timestamp) != time.Second { t.Fatalf("decoded frame = %+v, want payload=%q ts=1000000", frame, payload) } } @@ -825,7 +825,7 @@ func TestTrackPublishConsume(t *testing.T) { } defer consumer.Cancel() - if err := track.WriteFrame(moq.Frame{Payload: []byte("hello"), Timestamp: ts(12_345 * time.Microsecond)}); err != nil { + if err := track.WriteFrame(moq.Frame{Payload: []byte("hello"), Timestamp: ts(12_345)}); err != nil { t.Fatal(err) } @@ -836,7 +836,7 @@ func TestTrackPublishConsume(t *testing.T) { if frame == nil { t.Fatal("expected a frame") } - if string(frame.Payload) != "hello" || frame.Timestamp == nil || *frame.Timestamp != 12_345*time.Microsecond { + if string(frame.Payload) != "hello" || frame.Timestamp == nil || *frame.Timestamp != *ts(12_345) { t.Fatalf("frame = %+v, want payload=hello ts=12345", frame) } @@ -849,7 +849,7 @@ func TestTrackPublishConsume(t *testing.T) { t.Fatal(err) } defer groupConsumer.Cancel() - if err := group.WriteFrame(moq.Frame{Payload: []byte("group"), Timestamp: ts(23_456 * time.Microsecond)}); err != nil { + if err := group.WriteFrame(moq.Frame{Payload: []byte("group"), Timestamp: ts(23_456)}); err != nil { t.Fatal(err) } if err := group.Finish(); err != nil { @@ -862,7 +862,7 @@ func TestTrackPublishConsume(t *testing.T) { if frame == nil { t.Fatal("expected a group frame") } - if string(frame.Payload) != "group" || frame.Timestamp == nil || *frame.Timestamp != 23_456*time.Microsecond { + if string(frame.Payload) != "group" || frame.Timestamp == nil || *frame.Timestamp != *ts(23_456) { t.Fatalf("frame = %+v, want payload=group ts=23456", frame) } } @@ -884,7 +884,7 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { if err != nil { t.Fatal(err) } - if err := group.WriteFrame(moq.Frame{Payload: []byte("x"), Timestamp: ts(time.Duration(i) * time.Millisecond)}); err != nil { + if err := group.WriteFrame(moq.Frame{Payload: []byte("x"), Timestamp: ts(uint64(i) * 1000)}); err != nil { t.Fatal(err) } if err := group.Finish(); err != nil { @@ -945,7 +945,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) { if err := empty.Finish(); err != nil { t.Fatal(err) } - if err := track.WriteFrame(moq.Frame{Payload: []byte("populated"), Timestamp: ts(2_000 * time.Microsecond)}); err != nil { + if err := track.WriteFrame(moq.Frame{Payload: []byte("populated"), Timestamp: ts(2_000)}); err != nil { t.Fatal(err) } @@ -953,7 +953,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != "populated" || frame.Timestamp == nil || *frame.Timestamp != 2_000*time.Microsecond { + if frame == nil || string(frame.Payload) != "populated" || frame.Timestamp == nil || *frame.Timestamp != *ts(2_000) { t.Fatalf("frame = %+v, want payload=populated ts=2000", frame) } } @@ -1063,7 +1063,7 @@ func TestDynamicTrackRequest(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != 0 { + if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != *ts(0) { t.Fatalf("frame = %+v, want payload=%q ts=0", frame, payload) } if err := track.Finish(); err != nil { @@ -1143,7 +1143,7 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) { defer mediaConsumer.Cancel() payload := []byte("dynamic opus frame") - if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(20_000 * time.Microsecond)}); err != nil { + if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(20_000)}); err != nil { t.Fatal(err) } @@ -1156,7 +1156,7 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) { t.Fatalf("expected a media frame, got %T", read) } frame := &value.Frame - if string(frame.Payload) != string(payload) || uint64(frame.Timestamp.Microseconds()) != 20_000 { + if string(frame.Payload) != string(payload) || moq.TimestampToDuration(frame.Timestamp) != 20*time.Millisecond { t.Fatalf("frame = %+v, want payload=%q ts=20000", frame, payload) } // The explicit pause marker is an encoder end even while the track stays open. @@ -1170,7 +1170,7 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) { if err != nil { t.Fatal(err) } - if value, ok := end.(moqmedia.ReadEnd); !ok || value.End != 20_000*time.Microsecond { + if value, ok := end.(moqmedia.ReadEnd); !ok || moq.TimestampToDuration(value.End) != 20*time.Millisecond { t.Fatalf("expected encoder end, got %T", end) } if next, err := mediaConsumer.Next(ctx); next != nil || err != nil { @@ -1811,7 +1811,8 @@ func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { // us is a raw frame's optional timestamp in microseconds. func us(v uint64) *uint64 { return &v } -func ts(d time.Duration) *time.Duration { return &d } +// ts is a presentation time in microseconds, the scale timedInfo declares. +func ts(us uint64) *moq.Timestamp { return &moq.Timestamp{Value: us, Scale: 1_000_000} } // timedInfo declares the microsecond timeline used by timed raw fixtures. func timedInfo() *moq.TrackInfo { diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index a179024d830..aa808095ccc 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -206,31 +206,19 @@ func (t *TrackProducer) CreateGroup(sequence uint64) (*GroupProducer, error) { // WriteFrame writes frame as a single-frame group. func (t *TrackProducer) WriteFrame(frame Frame) error { - f, err := frame.ffi() - if err != nil { - return err - } - return t.inner.WriteFrame(f) + return t.inner.WriteFrame(frame) } // AppendDatagram sends frame as a best-effort datagram and returns the sequence number // assigned to it. Payloads are capped at 1200 bytes. There is no stream fallback. func (t *TrackProducer) AppendDatagram(frame Frame) (uint64, error) { - f, err := frame.ffi() - if err != nil { - return 0, err - } - return t.inner.AppendDatagram(f) + return t.inner.AppendDatagram(frame) } // InsertDatagram sends frame as a best-effort datagram at an explicit sequence, for a // caller that allocates its own. AppendDatagram continues after the largest one. func (t *TrackProducer) InsertDatagram(sequence uint64, frame Frame) error { - f, err := frame.ffi() - if err != nil { - return err - } - return t.inner.InsertDatagram(sequence, f) + return t.inner.InsertDatagram(sequence, frame) } // Largest reports the newest group or datagram written, at its newest frame, or nil @@ -290,11 +278,7 @@ func (g *GroupProducer) Consume() (*GroupConsumer, error) { // WriteFrame appends frame to the group. func (g *GroupProducer) WriteFrame(frame Frame) error { - f, err := frame.ffi() - if err != nil { - return err - } - return g.inner.WriteFrame(f) + return g.inner.WriteFrame(frame) } // Finish marks the group complete. The handle remains so Abort can still run. diff --git a/go/wrapper/records.go b/go/wrapper/records.go index 70bf887b02b..5ce0c0d6305 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -1,66 +1,53 @@ package moq import ( + "fmt" "math" + "math/bits" "time" ffi "moq.dev/moq-ffi/moq" "moq.dev/moq/internal/bridge" ) -// moq-ffi spells media timestamps as integer microseconds. These records mirror -// the generated ones with time.Duration timestamps and convert at the boundary. +// Timestamp is an exact media time: Value units at Scale units per second, with Value +// at most 2^61 - 1 and Scale non-zero and at most 2^62 - 1. A read carries the track's +// scale, so a tick such as 90 kHz survives a read and republish exactly. +type Timestamp = ffi.MoqTimestamp -// fromMicros saturates past time.Duration's ~292 years rather than wrapping to -// a negative duration. -func fromMicros(us uint64) time.Duration { - if us > uint64(math.MaxInt64/int64(time.Microsecond)) { - return time.Duration(math.MaxInt64) +// TimestampFromDuration converts d exactly, at nanosecond scale, refusing a negative d. +func TimestampFromDuration(d time.Duration) (Timestamp, error) { + if d < 0 { + return Timestamp{}, fmt.Errorf("negative timestamp: %v", d) } - return time.Duration(us) * time.Microsecond + return Timestamp{Value: uint64(d), Scale: uint64(time.Second)}, nil } -func optFromMicros(us *uint64) *time.Duration { - if us == nil { - return nil +// TimestampToDuration converts t to a time.Duration, rounded down to a whole +// nanosecond, saturating past time.Duration's ~292 years. It panics on a zero +// Scale, which no read returns. +func TimestampToDuration(t Timestamp) time.Duration { + if t.Scale == 0 { + panic("moq: timestamp with a zero scale") } - d := fromMicros(*us) - return &d + hi, lo := bits.Mul64(t.Value, uint64(time.Second)) + if hi >= t.Scale { + return time.Duration(math.MaxInt64) + } + ns, _ := bits.Div64(hi, lo, t.Scale) + if ns > math.MaxInt64 { + return time.Duration(math.MaxInt64) + } + return time.Duration(ns) } // Frame is a raw track frame: a payload and its presentation timestamp. // Timestamp is nil on an untimed track, on both publish and receive. -type Frame struct { - Payload []byte - Timestamp *time.Duration -} - -func (f Frame) ffi() (ffi.MoqFrame, error) { - us, err := bridge.OptionalDuration(f.Timestamp, "timestamp") - return ffi.MoqFrame{Payload: f.Payload, TimestampUs: us}, err -} - -func frameFromFFI(f *ffi.MoqFrame) *Frame { - if f == nil { - return nil - } - return &Frame{Payload: f.Payload, Timestamp: optFromMicros(f.TimestampUs)} -} +type Frame = ffi.MoqFrame // Datagram is a best-effort track datagram as received: sequence number, timestamp // (nil from an untimed track), and payload. -type Datagram struct { - Sequence uint64 - Timestamp *time.Duration - Payload []byte -} - -func datagramFromFFI(d *ffi.MoqDatagram) *Datagram { - if d == nil { - return nil - } - return &Datagram{Sequence: d.Sequence, Timestamp: optFromMicros(d.TimestampUs), Payload: d.Payload} -} +type Datagram = ffi.MoqDatagram // Subscription holds subscriber-side delivery preferences: priority, the max delay // a non-latest group may fall behind before it is skipped (zero skips at once, nil diff --git a/go/wrapper/records_internal_test.go b/go/wrapper/records_internal_test.go index b9e613fad0d..725d10d15d1 100644 --- a/go/wrapper/records_internal_test.go +++ b/go/wrapper/records_internal_test.go @@ -6,26 +6,59 @@ import ( "time" ) -// A peer's delay or max age can pass time.Duration's ~292 years, which must read as -// the longest duration rather than wrap to a negative one that is already expired. -func TestFromMicrosSaturates(t *testing.T) { - limit := uint64(math.MaxInt64 / int64(time.Microsecond)) +// A duration converts at its own nanosecond scale, so nothing rounds on the way in. +func TestTimestampFromDuration(t *testing.T) { + got, err := TimestampFromDuration(1500 * time.Millisecond) + if err != nil { + t.Fatal(err) + } + if want := (Timestamp{Value: 1_500_000_000, Scale: 1_000_000_000}); got != want { + t.Fatalf("TimestampFromDuration(1.5s) = %+v, want %+v", got, want) + } + if got := TimestampToDuration(got); got != 1500*time.Millisecond { + t.Fatalf("round trip = %v, want 1.5s", got) + } + if _, err := TimestampFromDuration(-time.Nanosecond); err == nil { + t.Fatal("negative duration converted") + } +} + +// Converting to a duration rounds down to a whole nanosecond, and a time past +// time.Duration's ~292 years reads as the longest duration rather than wrapping. +func TestTimestampToDuration(t *testing.T) { cases := []struct { - us uint64 + in Timestamp want time.Duration }{ - {us: 1, want: time.Microsecond}, - {us: limit, want: time.Duration(limit) * time.Microsecond}, - {us: limit + 1, want: time.Duration(math.MaxInt64)}, - {us: math.MaxUint64, want: time.Duration(math.MaxInt64)}, + {Timestamp{Value: 0, Scale: 90_000}, 0}, + // 11111.1 ns, 666666666.6 ns, and half a nanosecond all round down. + {Timestamp{Value: 1, Scale: 90_000}, 11_111}, + {Timestamp{Value: 2, Scale: 3}, 666_666_666}, + {Timestamp{Value: 1, Scale: 2_000_000_000}, 0}, + {Timestamp{Value: 1001, Scale: 30_000}, 33_366_666}, + {Timestamp{Value: math.MaxInt64, Scale: 1_000_000_000}, math.MaxInt64}, + {Timestamp{Value: math.MaxInt64/1000 + 1, Scale: 1_000_000}, math.MaxInt64}, + {Timestamp{Value: 1<<61 - 1, Scale: 1}, math.MaxInt64}, + {Timestamp{Value: math.MaxUint64, Scale: math.MaxUint64}, time.Second}, } for _, c := range cases { - if got := fromMicros(c.us); got != c.want { - t.Errorf("fromMicros(%d) = %v, want %v", c.us, got, c.want) + if got := TimestampToDuration(c.in); got != c.want { + t.Errorf("TimestampToDuration(%+v) = %d, want %d", c.in, got, c.want) } } } +// A zero scale, such as an unset Timestamp{}, panics rather than reading as the +// longest duration. +func TestTimestampToDurationZeroScale(t *testing.T) { + defer func() { + if recover() == nil { + t.Fatal("TimestampToDuration(Timestamp{}) did not panic") + } + }() + TimestampToDuration(Timestamp{}) +} + // DefaultSubscription carries moq-net's zero max delay, while the zero Subscription // leaves it nil, which sets no subscriber limit. func TestDefaultSubscriptionMaxDelay(t *testing.T) { diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index b3f78bdebd5..5507f55d70c 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -199,7 +199,7 @@ func benchThroughput(b *testing.B, c benchCase) { done <- err return } - want := time.Duration(n*frames+f) * time.Microsecond + want := moq.Timestamp{Value: uint64(n*frames + f), Scale: 1_000_000} if frame == nil || !bytes.Equal(frame.Payload, payload) || frame.Timestamp == nil || *frame.Timestamp != want { done <- fmt.Errorf("missing, reordered, or corrupt frame %d of round %d", f, n) return @@ -214,7 +214,7 @@ func benchThroughput(b *testing.B, c benchCase) { return err } for f := range frames { - timestamp := time.Duration(n*frames+f) * time.Microsecond + timestamp := moq.Timestamp{Value: uint64(n*frames + f), Scale: 1_000_000} if err := group.WriteFrame(moq.Frame{Payload: payload, Timestamp: ×tamp}); err != nil { return err } diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index 1b4ed49485b..a7d0465e245 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -92,8 +92,7 @@ func (g *GroupConsumer) Sequence() uint64 { // ReadFrame returns the next raw frame, or (nil, nil) when the group ends. func (g *GroupConsumer) ReadFrame(ctx context.Context) (*Frame, error) { - frame, err := bridge.Call(ctx, g.inner.Cancel, g.inner.ReadFrame) - return frameFromFFI(frame), err + return bridge.Call(ctx, g.inner.Cancel, g.inner.ReadFrame) } // All ranges over raw frames until the group ends or the loop breaks. @@ -147,15 +146,13 @@ func (t *TrackConsumer) group(ctx context.Context, next func(context.Context) (* // Cancelling the context cancels this consumer, not just this call: see // package docs. func (t *TrackConsumer) ReadFrame(ctx context.Context) (*Frame, error) { - frame, err := bridge.Call(ctx, t.inner.Cancel, t.inner.ReadFrame) - return frameFromFFI(frame), err + return bridge.Call(ctx, t.inner.Cancel, t.inner.ReadFrame) } // RecvDatagram returns the next best-effort datagram in arrival order, or // (nil, nil) when the track ends. func (t *TrackConsumer) RecvDatagram(ctx context.Context) (*Datagram, error) { - datagram, err := bridge.Call(ctx, t.inner.Cancel, t.inner.RecvDatagram) - return datagramFromFFI(datagram), err + return bridge.Call(ctx, t.inner.Cancel, t.inner.RecvDatagram) } // Info returns the publisher-side track properties learned during subscription. @@ -201,9 +198,9 @@ type VideoDecodedFrame struct { inner *ffi.MoqVideoDecodedFrame } -// TimestampUs is the presentation timestamp in microseconds. -func (f *VideoDecodedFrame) TimestampUs() uint64 { - return f.inner.TimestampUs() +// Timestamp is the presentation timestamp. +func (f *VideoDecodedFrame) Timestamp() Timestamp { + return f.inner.Timestamp() } // Width is the decoded width in pixels. diff --git a/go/wrapper/types.go b/go/wrapper/types.go index 18012e03b85..47a52311321 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -19,7 +19,7 @@ type ( AudioEncoderOutput = ffi.MoqAudioEncoderOutput // AudioSampleFormat is a raw PCM sample layout, mirroring WebCodecs AudioData.format. AudioSampleFormat = ffi.MoqAudioSampleFormat - // AudioFrame is one audio frame: PCM payload plus a presentation timestamp in microseconds. + // AudioFrame is one audio frame: PCM payload plus a presentation Timestamp. AudioFrame = ffi.MoqAudioFrame // ConnectionPhase is a connection lifecycle transition reported by Session.State. ConnectionPhase = ffi.MoqConnectionPhase @@ -66,7 +66,7 @@ type ( AnchorAbsolute = ffi.MoqAnchorAbsolute // AnchorRelative is the group Groups before the latest one, clamped to group 0: 0 is the latest. AnchorRelative = ffi.MoqAnchorRelative - // AnchorTime is the group containing TimestampUs, a presentation time in microseconds. + // AnchorTime is the group containing a presentation Timestamp. AnchorTime = ffi.MoqAnchorTime // Order is which of a subscription's pending groups the publisher sends first. Order = ffi.MoqOrder @@ -86,7 +86,7 @@ type ( VideoEncoderInput = ffi.MoqVideoEncoderInput // VideoEncoderOutput configures the video codec, bitrate, keyframe interval, and backend preference. VideoEncoderOutput = ffi.MoqVideoEncoderOutput - // VideoFrame is one raw video frame: pixels in the configured layout plus a presentation timestamp in microseconds. + // VideoFrame is one raw video frame: pixels in the configured layout plus a presentation Timestamp. VideoFrame = ffi.MoqVideoFrame // VideoEncoderKind selects the encoder implementation. Build one with // AutoEncoder, HardwareEncoder, SoftwareEncoder, or NamedEncoder. diff --git a/go/wrapper/video/video.go b/go/wrapper/video/video.go index 17eb552ce7e..fd078739104 100644 --- a/go/wrapper/video/video.go +++ b/go/wrapper/video/video.go @@ -38,26 +38,10 @@ type Gop = ffi.MoqVideoGop func Keyframe(interval uint32) Gop { return ffi.MoqVideoGopKeyframe{Interval: interval} } // Frame is one raw picture with its presentation timestamp. -type Frame struct { - Timestamp time.Duration - Data []byte -} - -func (f Frame) ffi() (ffi.MoqVideoFrame, error) { - us, err := bridge.Duration(f.Timestamp, "video timestamp") - return ffi.MoqVideoFrame{TimestampUs: us, Data: f.Data}, err -} +type Frame = ffi.MoqVideoFrame // Packet is one encoded access unit from an Encoder. -type Packet struct { - Timestamp time.Duration - Data []byte - Keyframe bool -} - -func packet(raw ffi.MoqVideoPacket) Packet { - return Packet{Timestamp: time.Duration(raw.TimestampUs) * time.Microsecond, Data: raw.Data, Keyframe: raw.Keyframe} -} +type Packet = ffi.MoqVideoPacket // DecoderOutput configures an optional resize, a delay, whether frames keep the decoder's surface (macOS only), and where to start. type DecoderOutput struct { @@ -135,11 +119,7 @@ func (p *Producer) Demand() (*moq.TrackDemand, error) { // Write encodes and publishes one raw picture in the configured input layout. func (p *Producer) Write(value Frame) error { - raw, err := value.ffi() - if err != nil { - return err - } - return p.inner.Write(raw) + return p.inner.Write(value) } // Cut starts a new group at the next written picture. @@ -172,22 +152,9 @@ func NewEncoder(input EncoderInput, output EncoderOutput) (*Encoder, error) { return &Encoder{inner}, nil } -func packets(raw []ffi.MoqVideoPacket) []Packet { - out := make([]Packet, len(raw)) - for i := range raw { - out[i] = packet(raw[i]) - } - return out -} - // Encode encodes one picture, returning any access units now available. func (e *Encoder) Encode(value Frame) ([]Packet, error) { - raw, err := value.ffi() - if err != nil { - return nil, err - } - result, err := e.inner.Encode(raw) - return packets(result), err + return e.inner.Encode(value) } // Cut forces the next encoded picture to start a new group. @@ -197,10 +164,10 @@ func (e *Encoder) Cut() error { return e.inner.Cut() } func (e *Encoder) SetBitrate(value uint64) error { return e.inner.SetBitrate(value) } // Flush drains buffered access units and keeps the encoder open. -func (e *Encoder) Flush() ([]Packet, error) { raw, err := e.inner.Flush(); return packets(raw), err } +func (e *Encoder) Flush() ([]Packet, error) { return e.inner.Flush() } // Finish drains and closes the encoder. -func (e *Encoder) Finish() ([]Packet, error) { raw, err := e.inner.Finish(); return packets(raw), err } +func (e *Encoder) Finish() ([]Packet, error) { return e.inner.Finish() } // Consumer subscribes to a video rendition and yields decoded frames. type Consumer struct{ inner *ffi.MoqVideoConsumer } @@ -231,7 +198,7 @@ type ReadFrame struct { // loss precedes it, and what follows does not continue it. type ReadGap struct { // Timestamp is the furthest presentation point already read. - Timestamp time.Duration + Timestamp moq.Timestamp // Duration is an upper bound on how long until the next picture resumes. Duration time.Duration } @@ -241,7 +208,7 @@ type ReadGap struct { // fresh encoder. type ReadEnd struct { // End is where the stopped encoder's media stops. - End time.Duration + End moq.Timestamp } func (ReadFrame) read() {} @@ -269,9 +236,9 @@ func (d *Consumer) Next(ctx context.Context) (Read, error) { case ffi.MoqVideoReadFrame: return ReadFrame{Frame: bridge.VideoDecodedFrame(read.Frame).(*moq.VideoDecodedFrame)}, nil case ffi.MoqVideoReadGap: - return ReadGap{Timestamp: time.Duration(read.TimestampUs) * time.Microsecond, Duration: read.Duration}, nil + return ReadGap{Timestamp: read.Timestamp, Duration: read.Duration}, nil case ffi.MoqVideoReadEnd: - return ReadEnd{End: time.Duration(read.EndUs) * time.Microsecond}, nil + return ReadEnd{End: read.End}, nil } return nil, fmt.Errorf("unknown video read: %T", *raw) } diff --git a/kt/README.md b/kt/README.md index 1531c2b0efa..1fb202ee284 100644 --- a/kt/README.md +++ b/kt/README.md @@ -60,9 +60,9 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **Flow extensions** (`Flows.kt`): `updates()`, `groups()`, and `frames()` turn the pull-based consumers into coroutine `Flow`s with cancellation wired through. - **Media** (`dev.moq.media`): catalog, importers, and container consumers, with `catalog(broadcast)` for a one-shot catalog read and `frames()` for container-decoded media. - **Fetched media**: `dev.moq.media.GroupConsumer.fetch(...).frames()` streams the decoded frames of one retained group, then completes. `dev.moq.media.GroupConsumer(group, container)` decodes a raw group instead, such as one from `recvGroup()` for arrival-order reads. -- **Timestamp extensions** (`Durations.kt`): the FFI carries media timestamps as microsecond integers, so `frame.timestamp` and its siblings read back as a `kotlin.time.Duration`. Durations such as `stats.rtt` are already `java.time.Duration`. +- **Timestamp conversions** (`Timestamp.kt`): media timestamps are exact `Timestamp(value, scale)` records. `Duration.toTimestamp()` builds one exactly at nanosecond scale, and `Timestamp.toDuration()` reads one back as a `kotlin.time.Duration`, rounded down to a whole nanosecond. Durations such as `stats.rtt` are already `java.time.Duration`. - **`logLevel(...)`**: configures native Rust tracing without importing the raw bindings package. -- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence, and `insertDatagram(sequence, frame)` takes the caller's own; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. +- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestamp))` sends one best-effort frame and returns its sequence, and `insertDatagram(sequence, frame)` takes the caller's own; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. ## Versioning @@ -97,7 +97,7 @@ kt/ moq/ build.gradle.kts Pure-Kotlin wrapper; coordinates dev.moq:moq src/ - jvmAndAndroidMain/kotlin/dev/moq/ Wrapper sources (Moq, Server, Aliases, Flows, Durations, Errors) + jvmAndAndroidMain/kotlin/dev/moq/ Wrapper sources (Moq, Server, Aliases, Flows, Timestamp, Errors) jvmAndAndroidTest/ Facade smoke test ``` diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index f52c572e76b..1074bf998b3 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -162,6 +162,9 @@ typealias Datagram = uniffi.moq.MoqDatagram /** A payload plus the timestamp it should be presented at. */ typealias Frame = uniffi.moq.MoqFrame +/** An exact media timestamp: `value` units at `scale` units per second. */ +typealias Timestamp = uniffi.moq.MoqTimestamp + /** * How a broadcast advertises its exact path: its static production cost (lower wins) and the * publisher epoch it serves (null when unknown). @@ -200,7 +203,7 @@ typealias AnchorAbsolute = uniffi.moq.MoqAnchor.Absolute /** The group `groups` before the latest one, clamped to group 0: 0 is the latest. */ typealias AnchorRelative = uniffi.moq.MoqAnchor.Relative -/** The group containing `timestampUs`, a presentation time in microseconds. */ +/** The group containing `timestamp`, a presentation time. */ typealias AnchorTime = uniffi.moq.MoqAnchor.Time /** Which pending group the publisher sends first: `ASCENDING` or `DESCENDING`. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt deleted file mode 100644 index dc34a9985a0..00000000000 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt +++ /dev/null @@ -1,30 +0,0 @@ -package dev.moq - -import kotlin.time.Duration -import kotlin.time.Duration.Companion.microseconds - -// The FFI surface carries media timestamps as microsecond integers; durations -// already cross as java.time.Duration. Read the timestamps back as a Duration. -// These are extension properties on the typealiased records, so the `*Us` -// fields stay available for anyone building a record to send back across the -// boundary. - -/** Presentation timestamp, or null for an untimed frame. */ -val Frame.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - -/** Presentation timestamp, or null for an untimed datagram. */ -val Datagram.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - -/** Presentation timestamp of the first sample. */ -val AudioFrame.timestamp: Duration - get() = timestampUs.toLong().microseconds - -/** Presentation timestamp. */ -val VideoFrame.timestamp: Duration - get() = timestampUs.toLong().microseconds - -/** Presentation timestamp. */ -val VideoDecodedFrame.timestamp: Duration - get() = timestampUs().toLong().microseconds diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt new file mode 100644 index 00000000000..e6675856781 --- /dev/null +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt @@ -0,0 +1,34 @@ +package dev.moq + +import java.math.BigInteger +import kotlin.time.Duration +import kotlin.time.Duration.Companion.nanoseconds +import kotlin.time.Duration.Companion.seconds + +/** + * This timestamp as a [Duration], rounded down to a whole nanosecond. + * + * The [Timestamp] itself is exact; keep it, not the duration, to republish a tick such as 90 kHz. + * Throws [IllegalArgumentException] past [Duration]'s range, about 146 million years. + */ +fun Timestamp.toDuration(): Duration { + // The sub-second remainder times a billion can exceed 64 bits. + val remainder = (value % scale).toString().toBigInteger() + val divisor = scale.toString().toBigInteger() + val nanos = remainder * BigInteger.valueOf(1_000_000_000L) / divisor + val duration = (value / scale).toLong().seconds + nanos.toLong().nanoseconds + // Duration saturates to infinite instead of failing. + require(duration.isFinite()) { "timestamp $value/$scale s does not fit in a Duration" } + return duration +} + +/** + * This duration as an exact [Timestamp] at nanosecond scale. + * + * Throws [IllegalArgumentException] when negative; a write refuses one past the value bound with + * `MoqException.TimeOverflow`. + */ +fun Duration.toTimestamp(): Timestamp { + require(!isNegative()) { "a timestamp cannot be negative: $this" } + return Timestamp(value = inWholeNanoseconds.toULong(), scale = 1_000_000_000uL) +} diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt index c39e89751ca..b7a7ffb3e31 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt @@ -36,7 +36,7 @@ typealias ReadFrame = uniffi.moq.MoqAudioRead.Frame /** Media after what was already read was lost; what follows does not continue it. */ typealias ReadGap = uniffi.moq.MoqAudioRead.Gap -/** The publisher stopped its encoder; frames starting before `endUs` are its remaining media. */ +/** The publisher stopped its encoder; frames starting before `end` are its remaining media. */ typealias ReadEnd = uniffi.moq.MoqAudioRead.End /** One encoded payload from an [Encoder]. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt index b0bade746de..36ef697f80d 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt @@ -11,9 +11,8 @@ package dev.moq.json // val reader = SnapshotConsumer(consumer.subscribeTrack("status", null)) import dev.moq.MoqJson +import dev.moq.Timestamp import dev.moq.pull -import kotlin.time.Duration -import kotlin.time.Duration.Companion.microseconds import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.map import kotlinx.serialization.serializer @@ -62,22 +61,8 @@ typealias WindowEventSkip = uniffi.moq.MoqJsonWindowEvent.Skip /** A [WindowEvent] and the timestamp of the frame that carried it. */ typealias WindowTimed = uniffi.moq.MoqJsonWindowTimed -/** - * The frame's timestamp on the broadcast clock, or null when untimed. Rounded down to a whole - * microsecond, so a tick on a track like 90 kHz may not survive a read and republish exactly. - */ -val Value.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - -/** - * The frame's timestamp on the broadcast clock, or null when untimed. A record first learned of - * from a group's restatement carries that frame's time, not its original push time. - */ -val WindowTimed.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - /** A decoded JSON value and its frame timestamp on the broadcast clock, or null when untimed. */ -data class Timed(val value: T, val timestamp: Duration?) +data class Timed(val value: T, val timestamp: Timestamp?) /** Decode [Value.value] as [T], keeping the timestamp. */ inline fun Value.decode(): Timed = @@ -87,21 +72,21 @@ inline fun Value.decode(): Timed = * Publish [value] as a JSON snapshot, superseding the last. A no-op when unchanged. * * The `@Serializable` type is encoded with [MoqJson]. Pass an already-encoded `String` to serialize - * with another library: the member overload takes it unchanged. [timestampUs] is on the broadcast + * with another library: the member overload takes it unchanged. [timestamp] is on the broadcast * clock; null is untimed. */ -inline fun SnapshotProducer.update(value: T, timestampUs: ULong? = null) { - update(MoqJson.encodeToString(serializer(), value), timestampUs) +inline fun SnapshotProducer.update(value: T, timestamp: Timestamp? = null) { + update(MoqJson.encodeToString(serializer(), value), timestamp) } -/** Append [value] at [timestampUs] on the broadcast clock; null is untimed. */ -inline fun StreamProducer.append(value: T, timestampUs: ULong? = null) { - append(MoqJson.encodeToString(serializer(), value), timestampUs) +/** Append [value] at [timestamp] on the broadcast clock; null is untimed. */ +inline fun StreamProducer.append(value: T, timestamp: Timestamp? = null) { + append(MoqJson.encodeToString(serializer(), value), timestamp) } -/** Push [value] onto the window at [timestampUs] on the broadcast clock; null is untimed. */ -inline fun WindowProducer.push(value: T, timestampUs: ULong? = null) { - push(MoqJson.encodeToString(serializer(), value), timestampUs) +/** Push [value] onto the window at [timestamp] on the broadcast clock; null is untimed. */ +inline fun WindowProducer.push(value: T, timestamp: Timestamp? = null) { + push(MoqJson.encodeToString(serializer(), value), timestamp) } /** Decode the pushed record as [T]. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt index 5efd41eb105..38d759acc47 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt @@ -3,8 +3,6 @@ package dev.moq.media import dev.moq.Frame import dev.moq.MoqJson import dev.moq.pull -import kotlin.time.Duration -import kotlin.time.Duration.Companion.microseconds import kotlinx.coroutines.flow.Flow import kotlinx.serialization.serializer import uniffi.moq.MoqException @@ -158,10 +156,6 @@ suspend fun catalog(broadcast: dev.moq.BroadcastConsumer): Catalog { /** Stream of decoded frames from one finite media group. */ fun GroupConsumer.frames(): Flow = pull({ cancel() }) { next() } -/** Presentation timestamp of a container-decoded frame. */ -val MediaFrame.timestamp: Duration - get() = timestampUs.toLong().microseconds - /** * Set an application catalog section from a serializable value, encoded with [MoqJson]. * @@ -171,11 +165,3 @@ val MediaFrame.timestamp: Duration inline fun CatalogProducer.setSection(name: String, value: T) { setSection(name, MoqJson.encodeToString(serializer(), value)) } - -/** The furthest presentation point already read. */ -val ReadGap.timestamp: Duration - get() = timestampUs.toLong().microseconds - -/** Where the stopped encoder's media stops. */ -val ReadEnd.end: Duration - get() = endUs.toLong().microseconds diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 3d4efe82682..c82ead5ca1a 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -16,7 +16,6 @@ import dev.moq.json.WindowProducer import dev.moq.json.decode import dev.moq.json.events import dev.moq.json.push -import dev.moq.json.timestamp import dev.moq.json.update import dev.moq.json.valuesAs import dev.moq.media.* @@ -33,6 +32,8 @@ import kotlin.test.assertNotNull import kotlin.test.assertNull import kotlin.test.assertTrue import kotlin.time.Duration.Companion.milliseconds +import kotlin.time.Duration.Companion.nanoseconds +import kotlin.time.Duration.Companion.seconds import kotlinx.coroutines.async import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.first @@ -273,7 +274,12 @@ class SmokeTest { BroadcastProducer().use { broadcast -> val track = broadcast.publishTrack("events", TrackInfo(timescale = 1_000_000uL)) val group = track.appendGroup() - group.writeFrame(Frame(payload = "cached".encodeToByteArray(), timestampUs = 0uL)) + group.writeFrame( + Frame( + payload = "cached".encodeToByteArray(), + timestamp = Timestamp(0uL, 1_000_000uL), + ) + ) group.finish() val fetched = @@ -303,7 +309,7 @@ class SmokeTest { for (ms in 0uL until 3uL) { val group = track.appendGroup() group.writeFrame( - Frame(payload = "x".encodeToByteArray(), timestampUs = ms * 1_000uL) + Frame(payload = "x".encodeToByteArray(), timestamp = Timestamp(ms, 1_000uL)) ) group.finish() } @@ -328,11 +334,14 @@ class SmokeTest { track.appendGroup().finish() track.appendGroup().finish() track.writeFrame( - Frame(payload = "populated".encodeToByteArray(), timestampUs = 2_000uL) + Frame( + payload = "populated".encodeToByteArray(), + timestamp = 2.milliseconds.toTimestamp(), + ) ) val frame = consumer.readFrame() assertEquals("populated", frame?.payload?.decodeToString()) - assertEquals(2_000uL, frame?.timestampUs) + assertEquals(Timestamp(2_000uL, 1_000_000uL), frame?.timestamp) } } @@ -344,7 +353,7 @@ class SmokeTest { track.writeFrame(Frame(payload = "payload".encodeToByteArray())) val frame = consumer.readFrame() assertEquals("payload", frame?.payload?.decodeToString()) - assertNull(frame?.timestampUs) + assertNull(frame?.timestamp) assertNull(consumer.info().timescale) track.finish() } @@ -376,7 +385,10 @@ class SmokeTest { val (name, audio) = catalog(consumer).audio.entries.single() media.writeFrame( - Frame(payload = "opus frame".encodeToByteArray(), timestampUs = 5_000_000uL) + Frame( + payload = "opus frame".encodeToByteArray(), + timestamp = 5.seconds.toTimestamp(), + ) ) // Fetch while the track is still published: finishing the media producer @@ -400,7 +412,7 @@ class SmokeTest { assertEquals(1, frames.size) val frame = frames.single() assertEquals("opus frame", frame.payload.decodeToString()) - assertEquals(5_000_000uL, frame.timestampUs) + assertEquals(5.seconds, frame.timestamp.toDuration()) } } } @@ -422,13 +434,62 @@ class SmokeTest { assertNotNull(audio) } - /** Microsecond timestamps read back as a Duration. */ + /** A 90 kHz tick, a present zero, and an untimed frame survive a write and read exactly. */ + @Test + fun `timestamps round-trip exactly`() = runTest { + for (timestamp in listOf(Timestamp(1uL, 90_000uL), Timestamp(0uL, 90_000uL), null)) { + BroadcastProducer().use { broadcast -> + // A timed track refuses an untimed frame, so null goes to an untimed one. + val track = + broadcast.publishTrack( + "ticks", + timestamp?.let { TrackInfo(timescale = 90_000uL) }, + ) + val consumer = track.consume(null) + track.writeFrame(Frame(payload = ByteArray(0), timestamp = timestamp)) + assertEquals(timestamp, consumer.readFrame()?.timestamp) + } + } + } + + /** A zero scale, a scale past 2^62 - 1, and a value past 2^61 - 1 are refused at the write. */ @Test - fun `microsecond timestamps read back as durations`() { + fun `out of range timestamps are refused`() { + BroadcastProducer().use { broadcast -> + val track = broadcast.publishTrack("ticks", TrackInfo(timescale = 90_000uL)) + for (timestamp in + listOf( + Timestamp(1uL, 0uL), + Timestamp(1uL, 1uL shl 62), + Timestamp(1uL shl 61, 90_000uL), + )) { + assertFailsWith { + track.writeFrame(Frame(payload = ByteArray(0), timestamp = timestamp)) + } + } + } + } + + /** + * From a duration is exact at nanosecond scale; to a duration rounds down to a whole + * nanosecond. + */ + @Test + fun `timestamps convert to and from durations`() { + assertEquals(Timestamp(20_000_000uL, 1_000_000_000uL), 20.milliseconds.toTimestamp()) + assertFailsWith { (-1).nanoseconds.toTimestamp() } + assertEquals(11_111.nanoseconds, Timestamp(1uL, 90_000uL).toDuration()) + assertEquals(666_666_666.nanoseconds, Timestamp(2uL, 3uL).toDuration()) + assertEquals(0.nanoseconds, Timestamp(1uL, 2_000_000_000uL).toDuration()) + // The sub-second remainder times a billion overflows 64 bits at the largest scale, and the + // result is just under half a second. assertEquals( - 20.milliseconds, - Frame(payload = ByteArray(0), timestampUs = 20_000uL).timestamp, + 499_999_999.nanoseconds, + Timestamp((1uL shl 61) - 1uL, (1uL shl 62) - 1uL).toDuration(), ) + assertFailsWith { + Timestamp((1uL shl 61) - 1uL, 1uL).toDuration() + } assertNull(AudioEncoderOutput(codec = AudioCodec.opus()).frameDuration) } @@ -441,20 +502,20 @@ class SmokeTest { val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null)) for (n in 1..4) producer.update( Status(state = "live$n"), - timestampUs = n.toULong() * 1_000uL, + timestamp = n.milliseconds.toTimestamp(), ) // `next` yields every state in order; `latest` skips the buffered third. assertEquals( - Timed(Status(state = "live1"), 1.milliseconds), + Timed(Status(state = "live1"), Timestamp(1_000uL, 1_000_000uL)), consumer.next()?.decode(), ) assertEquals( - Timed(Status(state = "live2"), 2.milliseconds), + Timed(Status(state = "live2"), Timestamp(2_000uL, 1_000_000uL)), consumer.next()?.decode(), ) assertEquals( - Timed(Status(state = "live4"), 4.milliseconds), + Timed(Status(state = "live4"), Timestamp(4_000uL, 1_000_000uL)), consumer.latest()?.decode(), ) } @@ -470,24 +531,24 @@ class SmokeTest { val consumer = WindowConsumer(broadcast.consume().subscribeTrack("log", null)) for (n in 1..3) producer.push( Status(state = "live$n"), - timestampUs = n.toULong() * 1_000uL, + timestamp = Timestamp(n.toULong(), 1_000uL), ) - producer.pop(2uL, 4_000uL) + producer.pop(2uL, Timestamp(4uL, 1_000uL)) for (n in 0..2) { val timed = checkNotNull(consumer.next()) val push = assertIs(timed.event) assertEquals(n.toULong(), push.index) assertEquals(Status(state = "live${n + 1}"), push.decode()) - assertEquals((n + 1).milliseconds, timed.timestamp) + assertEquals((n + 1).milliseconds, timed.timestamp?.toDuration()) } val pop = checkNotNull(consumer.next()) assertEquals(WindowEventPop(0uL, 2uL), pop.event) - assertEquals(4.milliseconds, pop.timestamp) + assertEquals(4.milliseconds, pop.timestamp?.toDuration()) // The cut's new group restates record 2, which this reader already has. producer.cut() - producer.push(Status(state = "live4"), timestampUs = 5_000uL) + producer.push(Status(state = "live4"), timestamp = 5.milliseconds.toTimestamp()) producer.finish() val events = consumer.events().toList() assertEquals(1, events.size) @@ -771,7 +832,7 @@ class SmokeTest { ), ) // 2.5 ms of silence at 48 kHz mono f32: exactly one encoded frame. - fine.write(AudioFrame(timestampUs = 0uL, data = ByteArray(120 * 4))) + fine.write(AudioFrame(timestamp = Timestamp(0uL, 48_000uL), data = ByteArray(120 * 4))) fine.finish() assertFailsWith { @@ -912,7 +973,7 @@ class SmokeTest { for (i in 0 until 2) { audio.write( AudioFrame( - timestampUs = i.toULong() * 20_000uL, + timestamp = Timestamp(i.toULong() * 960uL, 48_000uL), data = ByteArray(960 * 4), ) ) @@ -965,7 +1026,9 @@ class SmokeTest { val rgba = ByteArray(320 * 240 * 4) { 0x80.toByte() } video.cut() for (i in 0 until 10) { - video.write(VideoFrame(timestampUs = i.toULong() * 33_333uL, data = rgba)) + video.write( + VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba) + ) } val consumer = origin.consume().request("video-decode-frame") @@ -977,7 +1040,9 @@ class SmokeTest { // Keep the encoder fed so the decoder sees frames after it joined. for (i in 10 until 40) { - video.write(VideoFrame(timestampUs = i.toULong() * 33_333uL, data = rgba)) + video.write( + VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba) + ) } assertIs(decoder.next()).frame.use { frame -> @@ -1013,7 +1078,7 @@ class SmokeTest { fun `encode audio with opus object`() { val input = AudioEncoderInput(format = AudioSampleFormat.F32, sampleRate = 48_000u, channels = 1u) - val silence = AudioFrame(timestampUs = 0uL, data = ByteArray(960 * 4)) + val silence = AudioFrame(timestamp = Timestamp(0uL, 48_000uL), data = ByteArray(960 * 4)) // The producer retains the codec, so releasing the codec and the // config in either order must still encode. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt index b4b908fb23d..8276d948267 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt @@ -9,7 +9,7 @@ val opusInit: ByteArray get() = TODO() val packet: ByteArray get() = TODO() -val pts: ULong +val pts: dev.moq.Timestamp get() = TODO() val rgba: ByteArray get() = TODO() diff --git a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt index 0e6e45da1d1..1fa325f5e59 100644 --- a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt +++ b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt @@ -106,7 +106,10 @@ class FfiBench { frame.payload.contentEquals(payload), "corrupt frame $f of round $n", ) - assertEquals((n * case.frames + f).toULong(), frame.timestampUs) + assertEquals( + Timestamp((n * case.frames + f).toULong(), 1_000_000uL), + frame.timestamp, + ) } } } @@ -117,7 +120,8 @@ class FfiBench { group.writeFrame( Frame( payload = payload, - timestampUs = (n * case.frames + f).toULong(), + timestamp = + Timestamp((n * case.frames + f).toULong(), 1_000_000uL), ) ) } diff --git a/py/moq-ffi/tests/exit_inside_callback.py b/py/moq-ffi/tests/exit_inside_callback.py index 6abe1fa4042..9e2ec2038de 100644 --- a/py/moq-ffi/tests/exit_inside_callback.py +++ b/py/moq-ffi/tests/exit_inside_callback.py @@ -63,7 +63,11 @@ async def main() -> None: subscriber = await consumer.subscribe_track("data", None) # Written once the read is parked, so the runtime thread delivers the wake. - asyncio.get_running_loop().call_later(0.05, track.write_frame, moq_ffi.MoqFrame(payload=b"hello", timestamp_us=0)) + asyncio.get_running_loop().call_later( + 0.05, + track.write_frame, + moq_ffi.MoqFrame(payload=b"hello", timestamp=moq_ffi.MoqTimestamp(value=0, scale=1_000_000)), + ) frame = await subscriber.read_frame() assert frame is not None # Flushed now: a write left for exit would hand the GIL over early. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 1ecfbba6f71..1a818fc109c 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -54,7 +54,6 @@ asyncio.run(main()) ```python import asyncio -from datetime import timedelta import moq @@ -70,9 +69,9 @@ async def main(): # Write frames # Audio has no keyframes, so `cut` is what gives it group boundaries. - audio.write_frame(payload, timestamp=timedelta(0)) + audio.write_frame(payload, timestamp=moq.Timestamp(0, 1_000)) audio.cut() - audio.write_frame(payload, timestamp=timedelta(milliseconds=20)) + audio.write_frame(payload, timestamp=moq.Timestamp(20, 1_000)) audio.cut() # A fresh epoch per run tells viewers a restart is a new broadcast. @@ -203,7 +202,7 @@ client = moq.Client( and do not keep it open. - `media.CatalogProducer(broadcast)` owns `set_video_properties`, `set_section`, and `remove_section`. It holds the broadcast weakly; writes fail with `Error.Closed` after closing - or releasing the broadcast. `.now()` returns its current media time as `timedelta` and fixes + or releasing the broadcast. `.now()` returns its current media time as a `Timestamp` and fixes the clock for subsequent producers. - `await media.CatalogConsumer.subscribe(broadcast)` streams catalog snapshots; `await media.catalog(broadcast)` reads one snapshot and releases its subscription. @@ -217,8 +216,8 @@ client = moq.Client( `TrackConsumer.recv_group()` for arrival-order reads, with container media time on each frame as it lands. -`media.TrackProducer.write_frame(payload, timestamp)` requires the caller's capture time as -`timedelta`; returned `media.MediaFrame.timestamp` uses it too. `demand()` owns the track name and +`media.TrackProducer.write_frame(payload, timestamp)` requires the caller's capture time as a +`Timestamp`; returned `media.MediaFrame.timestamp` uses it too. `demand()` owns the track name and subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish()` ends the import. ### Data @@ -270,9 +269,10 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting ### Types - **`media.Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`. -- **`Frame`**. `.payload: bytes`, `.timestamp: timedelta | None`. The unit of every write and every raw read; `None` means untimed when publishing or reading. -- **`media.MediaFrame`**. `.payload: bytes`, `.timestamp: timedelta`, `.keyframe: bool`. The frame variant of a media read. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. -- **`Datagram`**. `.sequence: int`, `.timestamp: timedelta | None`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. +- **`Timestamp`**. `.value: int` units at `.scale: int` units per second, exact at any scale such as 90 kHz. `Timestamp.from_timedelta(duration)` is exact at microsecond scale; `.to_timedelta()` rounds down to a whole microsecond. A write with a scale of 0 or past `2**62 - 1`, or a value past `2**61 - 1`, raises `Error.TimeOverflow`. +- **`Frame`**. `.payload: bytes`, `.timestamp: Timestamp | None`. The unit of every write and every raw read; `None` means untimed when publishing or reading. +- **`media.MediaFrame`**. `.payload: bytes`, `.timestamp: Timestamp`, `.keyframe: bool`. The frame variant of a media read. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. +- **`Datagram`**. `.sequence: int`, `.timestamp: Timestamp | None`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. - **`media.Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.enabled`, `.description`. - **`media.Video`**. `.codec`, `.coded: Dimensions`, `.display_aspect`, `.bitrate`, `.enabled`, `.framerate`, `.description`. A false `.enabled` means no frames are coming, so don't select the rendition. - **`Subscription`**. Subscriber delivery preferences: priority, staleness, and optional group range. diff --git a/py/moq-rs/benches/ffi.py b/py/moq-rs/benches/ffi.py index eeb1d1275fa..f5049c4cad2 100644 --- a/py/moq-rs/benches/ffi.py +++ b/py/moq-rs/benches/ffi.py @@ -10,7 +10,6 @@ import resource import time from dataclasses import dataclass -from datetime import timedelta from pathlib import Path from typing import Callable @@ -66,7 +65,7 @@ async def read(case: Case, consumer: moq.TrackConsumer, payload: bytes, n: int) frame = await group.read_frame() assert frame is not None, "group ended" assert frame.payload == payload, f"corrupt frame {f} of round {n}" - assert frame.timestamp == timedelta(microseconds=n * case.frames + f) + assert frame.timestamp == moq.Timestamp(n * case.frames + f, 1_000_000) async def throughput(case: Case, results: list[dict]) -> None: @@ -83,7 +82,7 @@ async def step(n: int) -> None: for track in tracks: group = track.append_group() for f in range(case.frames): - group.write_frame(payload, timedelta(microseconds=n * case.frames + f)) + group.write_frame(payload, moq.Timestamp(n * case.frames + f, 1_000_000)) group.finish() await asyncio.wait_for(asyncio.gather(*readers), ROUND_TIMEOUT) diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index 3c4f4b370cd..0db419d3370 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -182,7 +182,7 @@ broadcast, and producers advertise it in the catalog. ## Data types These records, enums, and objects are re-exported from the native `moq_ffi` bindings; the -wrapper groups them under `moq` and `moq.media`, with owned duration records at the boundary. Their fields are defined on the +wrapper groups them under `moq` and `moq.media`, with owned duration and timestamp records at the boundary. Their fields are defined on the Rust side ([`moq-ffi`](https://crates.io/crates/moq-ffi)). ```{eval-rst} @@ -194,6 +194,7 @@ Rust side ([`moq-ffi`](https://crates.io/crates/moq-ffi)). media.Catalog media.Container + Timestamp Frame media.MediaFrame Datagram diff --git a/py/moq-rs/examples/clock.py b/py/moq-rs/examples/clock.py index d7a89720d7c..7fd03a5a569 100644 --- a/py/moq-rs/examples/clock.py +++ b/py/moq-rs/examples/clock.py @@ -10,7 +10,7 @@ import argparse import asyncio -from datetime import datetime, timedelta, timezone +from datetime import datetime, timezone import moq @@ -24,13 +24,13 @@ async def publish(url: str, broadcast_name: str, track_name: str, insecure: bool while True: now = datetime.now(timezone.utc).replace(microsecond=0) - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group = track.append_group() group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp) current_minute = now.minute while now.minute == current_minute: - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group.write_frame(now.strftime("%S").encode(), timestamp) await asyncio.sleep(1 - datetime.now(timezone.utc).microsecond / 1_000_000) now = datetime.now(timezone.utc).replace(microsecond=0) diff --git a/py/moq-rs/examples/serve_clock.py b/py/moq-rs/examples/serve_clock.py index 6554372b081..5df6325cb1a 100644 --- a/py/moq-rs/examples/serve_clock.py +++ b/py/moq-rs/examples/serve_clock.py @@ -13,7 +13,7 @@ import argparse import asyncio -from datetime import datetime, timedelta, timezone +from datetime import datetime, timezone import moq @@ -31,13 +31,13 @@ async def run(bind: str, broadcast_name: str, track_name: str, host: str) -> Non try: while True: now = datetime.now(timezone.utc).replace(microsecond=0) - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group = track.append_group() group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp) current_minute = now.minute while now.minute == current_minute: - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group.write_frame(now.strftime("%S").encode(), timestamp) await asyncio.sleep(1 - datetime.now(timezone.utc).microsecond / 1_000_000) now = datetime.now(timezone.utc).replace(microsecond=0) diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index a992becf09f..9c25041308d 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -72,6 +72,7 @@ Range, Route, Subscription, + Timestamp, TrackInfo, VideoCodec, VideoDecodedFrame, @@ -137,6 +138,7 @@ "Server", "Session", "Subscription", + "Timestamp", "Tokens", "TrackConsumer", "TrackDemand", diff --git a/py/moq-rs/moq/_read.py b/py/moq-rs/moq/_read.py index 0a244d0c286..8fb88218b8b 100644 --- a/py/moq-rs/moq/_read.py +++ b/py/moq-rs/moq/_read.py @@ -5,7 +5,9 @@ from dataclasses import dataclass from datetime import timedelta -from ._records import _from_us +from moq_ffi import MoqTimestamp + +from ._records import Timestamp @dataclass(frozen=True) @@ -17,7 +19,7 @@ class Gap: furthest presentation point already read. """ - timestamp: timedelta + timestamp: Timestamp duration: timedelta @@ -29,12 +31,12 @@ class End: remaining media; the first at or past it comes from a fresh encoder. """ - end: timedelta + end: Timestamp -def _gap(timestamp_us: int, duration: timedelta) -> Gap: - return Gap(timestamp=_from_us(timestamp_us), duration=duration) +def _gap(timestamp: MoqTimestamp, duration: timedelta) -> Gap: + return Gap(timestamp=Timestamp._from_ffi(timestamp), duration=duration) -def _end(end_us: int) -> End: - return End(end=_from_us(end_us)) +def _end(end: MoqTimestamp) -> End: + return End(end=Timestamp._from_ffi(end)) diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 3ee125b765c..45a2bebfd46 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -1,8 +1,7 @@ """Root records the wrapper owns, as frozen dataclasses with Python defaults. -moq-ffi spells media timestamps as integer microseconds, so ``Frame`` and -``Datagram`` convert them to ``timedelta`` at the boundary. Durations already -cross as ``timedelta``. ``ClientTls`` lives here with the rest of the client +Media timestamps cross as exact :class:`Timestamp` records; durations cross as +``timedelta``. ``ClientTls`` lives here with the rest of the client config, so a bare string passed for a list is refused instead of splitting into characters. """ @@ -13,8 +12,10 @@ from dataclasses import dataclass from datetime import timedelta from importlib import metadata +from typing import ClassVar, cast from moq_ffi import ( + MoqAnchor, MoqBackoff, MoqClientTls, MoqCongestionControl, @@ -26,7 +27,11 @@ MoqQuicConfig, MoqRange, MoqSubscription, + MoqTimestamp, MoqTrackInfo, + MoqVideoDecodedFrame, + MoqVideoPixelFormat, + MoqVideoSurface, MoqWebSocketConfig, moq_subscription_defaults, ) @@ -43,29 +48,53 @@ def _implementation() -> str: return "moq-py/dev" -def _to_us(value: timedelta, name: str) -> int: - if value < timedelta(0): - raise ValueError(f"{name} must not be negative: {value}") - return value // _MICROSECOND +def _strs(value: Sequence[str], name: str) -> list[str]: + # A str is itself a Sequence[str], so list() would split it into characters. + if isinstance(value, str): + raise TypeError(f"{name} takes a sequence of strings, not a str: {value!r}") + return list(value) -def _opt_us(value: timedelta | None, name: str) -> int | None: - return None if value is None else _to_us(value, name) +@dataclass(frozen=True) +class Timestamp: + """An exact media timestamp: ``value`` units at ``scale`` units per second. + ``value`` is at most ``2**61 - 1`` and ``scale`` is non-zero and at most ``2**62 - 1``; + a write past either bound raises ``moq.Error.TimeOverflow``. A read carries the + track's timescale, and a write at another scale is floored to it. + """ -def _from_us(us: int) -> timedelta: - return timedelta(microseconds=us) + value: int + scale: int + @staticmethod + def from_timedelta(duration: timedelta) -> Timestamp: + """Exactly ``duration``, at microsecond scale since that is a ``timedelta``'s own unit.""" + if duration < timedelta(0): + raise ValueError(f"timestamp must not be negative: {duration}") + return Timestamp(duration // _MICROSECOND, 1_000_000) -def _strs(value: Sequence[str], name: str) -> list[str]: - # A str is itself a Sequence[str], so list() would split it into characters. - if isinstance(value, str): - raise TypeError(f"{name} takes a sequence of strings, not a str: {value!r}") - return list(value) + def to_timedelta(self) -> timedelta: + """This timestamp as a ``timedelta``, rounded down to a whole microsecond. + The timestamp itself is exact; keep it, not the ``timedelta``, to republish a tick such as 90 kHz. + """ + return timedelta(microseconds=self.value * 1_000_000 // self.scale) -def _opt_from_us(us: int | None) -> timedelta | None: - return None if us is None else _from_us(us) + def _ffi(self) -> MoqTimestamp: + return MoqTimestamp(value=self.value, scale=self.scale) + + @staticmethod + def _from_ffi(value: MoqTimestamp) -> Timestamp: + return Timestamp(value.value, value.scale) + + +def _opt_ts(value: Timestamp | None) -> MoqTimestamp | None: + return None if value is None else value._ffi() + + +def _opt_from_ts(value: MoqTimestamp | None) -> Timestamp | None: + return None if value is None else Timestamp._from_ffi(value) @dataclass(frozen=True) @@ -76,14 +105,14 @@ class Frame: """ payload: bytes - timestamp: timedelta | None = None + timestamp: Timestamp | None = None def _ffi(self) -> MoqFrame: - return MoqFrame(payload=self.payload, timestamp_us=_opt_us(self.timestamp, "timestamp")) + return MoqFrame(payload=self.payload, timestamp=_opt_ts(self.timestamp)) @staticmethod def _from_ffi(frame: MoqFrame) -> Frame: - return Frame(payload=frame.payload, timestamp=_opt_from_us(frame.timestamp_us)) + return Frame(payload=frame.payload, timestamp=_opt_from_ts(frame.timestamp)) @dataclass(frozen=True) @@ -94,18 +123,84 @@ class Datagram: """ sequence: int - timestamp: timedelta | None + timestamp: Timestamp | None payload: bytes @staticmethod def _from_ffi(datagram: MoqDatagram) -> Datagram: return Datagram( sequence=datagram.sequence, - timestamp=_opt_from_us(datagram.timestamp_us), + timestamp=_opt_from_ts(datagram.timestamp), payload=datagram.payload, ) +class Anchor: + """Where one end of a :class:`Range` falls, mirroring moq-net's ``track::Anchor``. + + Build one with ``Anchor.ABSOLUTE(group=...)``, ``Anchor.RELATIVE(groups=...)``, or + ``Anchor.TIME(timestamp=...)``. + """ + + ABSOLUTE: ClassVar[type[_AnchorAbsolute]] + RELATIVE: ClassVar[type[_AnchorRelative]] + TIME: ClassVar[type[_AnchorTime]] + + def _ffi(self) -> MoqAnchor: + raise TypeError("build an Anchor with Anchor.ABSOLUTE, Anchor.RELATIVE, or Anchor.TIME") + + +# The generated variants subclass MoqAnchor only at runtime, so each _ffi casts for pyright. +@dataclass(frozen=True) +class _AnchorAbsolute(Anchor): + """This group, delivered from its first frame.""" + + group: int + + def _ffi(self) -> MoqAnchor: + return cast(MoqAnchor, MoqAnchor.ABSOLUTE(group=self.group)) + + +@dataclass(frozen=True) +class _AnchorRelative(Anchor): + """The group this many before the latest, clamped to group 0: ``0`` is the latest group.""" + + groups: int + + def _ffi(self) -> MoqAnchor: + return cast(MoqAnchor, MoqAnchor.RELATIVE(groups=self.groups)) + + +@dataclass(frozen=True) +class _AnchorTime(Anchor): + """The group containing this presentation time. An untimed track refuses it.""" + + timestamp: Timestamp + + def _ffi(self) -> MoqAnchor: + return cast(MoqAnchor, MoqAnchor.TIME(timestamp=self.timestamp._ffi())) + + +Anchor.ABSOLUTE = _AnchorAbsolute +Anchor.RELATIVE = _AnchorRelative +Anchor.TIME = _AnchorTime + + +@dataclass(frozen=True) +class Range: + """A span of a track to deliver, from ``start`` to ``end``, ``None`` to keep following the live edge. + + A relative or time start is the first frame of its group, and a relative or time end + includes its whole group. An absolute end is exclusive. + """ + + start: Anchor + end: Anchor | None = None + + def _ffi(self) -> MoqRange: + return MoqRange(start=self.start._ffi(), end=None if self.end is None else self.end._ffi()) + + @dataclass(frozen=True) class Subscription: """Subscriber-side delivery preferences, mirroring moq-net's ``track::Subscription``. @@ -122,7 +217,7 @@ class Subscription: priority: int = 0 max_delay: timedelta | None = timedelta(0) - ranges: Sequence[MoqRange] | None = None + ranges: Sequence[Range] | None = None order: MoqOrder | None = None @classmethod @@ -136,7 +231,8 @@ def default(cls) -> Subscription: return cls( priority=defaults.priority, max_delay=defaults.max_delay, - ranges=defaults.ranges, + # The FFI defaults never restrict ranges, so there is no record to convert. + ranges=None, order=defaults.order, ) @@ -144,7 +240,7 @@ def _ffi(self) -> MoqSubscription: return MoqSubscription( priority=self.priority, max_delay=self.max_delay, - ranges=None if self.ranges is None else list(self.ranges), + ranges=None if self.ranges is None else [r._ffi() for r in self.ranges], order=self.order, ) @@ -360,3 +456,30 @@ def _from_ffi(grant: MoqGrant | None) -> Grant | None: subscribe=tuple(grant.subscribe), expires=grant.expires, ) + + +class VideoDecodedFrame: + """One decoded picture. It owns the decoder's buffer until garbage collected, so drop it promptly.""" + + def __init__(self, inner: MoqVideoDecodedFrame) -> None: + self._inner = inner + + def timestamp(self) -> Timestamp: + """The presentation timestamp, at the track's timescale.""" + return Timestamp._from_ffi(self._inner.timestamp()) + + def width(self) -> int: + """The picture's width in pixels.""" + return self._inner.width() + + def height(self) -> int: + """The picture's height in pixels.""" + return self._inner.height() + + def pixels(self, format: MoqVideoPixelFormat) -> bytes: + """The picture converted to tightly packed CPU pixels in ``format``.""" + return self._inner.pixels(format) + + def surface(self) -> MoqVideoSurface | None: + """The decoder's platform surface, when the decoder output asked for one.""" + return self._inner.surface() diff --git a/py/moq-rs/moq/audio.py b/py/moq-rs/moq/audio.py index 25e607111f6..79eeddeb41c 100644 --- a/py/moq-rs/moq/audio.py +++ b/py/moq-rs/moq/audio.py @@ -19,7 +19,7 @@ ) from ._read import End, Gap, _end, _gap -from ._records import _from_us, _to_us +from ._records import Timestamp from ._stream import _Stream from .media import Audio, AudioInit, CatalogProducer, DecodeStart, Delay from .publish import TrackDemand @@ -40,15 +40,15 @@ class Frame: """Interleaved PCM with its presentation timestamp.""" - timestamp: timedelta + timestamp: Timestamp data: bytes def _ffi(self) -> MoqAudioFrame: - return MoqAudioFrame(timestamp_us=_to_us(self.timestamp, "timestamp"), data=self.data) + return MoqAudioFrame(timestamp=self.timestamp._ffi(), data=self.data) @staticmethod def _from_ffi(value: MoqAudioFrame) -> Frame: - return Frame(timestamp=_from_us(value.timestamp_us), data=value.data) + return Frame(timestamp=Timestamp._from_ffi(value.timestamp), data=value.data) Read = Frame | Gap | End @@ -185,9 +185,9 @@ async def _next(self) -> Read | None: if isinstance(value, MoqAudioRead.FRAME): return Frame._from_ffi(value.frame) if isinstance(value, MoqAudioRead.GAP): - return _gap(value.timestamp_us, value.duration) + return _gap(value.timestamp, value.duration) if isinstance(value, MoqAudioRead.END): - return _end(value.end_us) + return _end(value.end) raise TypeError(f"unknown audio read: {value!r}") @property diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index 51a0c9daa5c..e8a029e3dff 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -14,7 +14,6 @@ import json from dataclasses import dataclass -from datetime import timedelta from typing import Any from moq_ffi import ( @@ -32,7 +31,7 @@ ) from . import publish, subscribe -from ._records import _opt_from_us, _opt_us +from ._records import Timestamp, _opt_from_ts, _opt_ts from ._stream import _Stream from .publish import BroadcastProducer, TrackDemand @@ -55,19 +54,17 @@ class Timed: """A parsed JSON value and the timestamp of the frame that carried it. - ``timestamp`` is on the broadcast clock, and ``None`` on an untimed track. It is - rounded down to a whole microsecond, so a tick on a track like 90 kHz may not - survive a read and republish exactly. + ``timestamp`` is on the broadcast clock, and ``None`` on an untimed track. """ value: Any - timestamp: timedelta | None + timestamp: Timestamp | None @staticmethod def _from_ffi(value: MoqJsonValue | None) -> Timed | None: if value is None: return None - return Timed(value=json.loads(value.value), timestamp=_opt_from_us(value.timestamp_us)) + return Timed(value=json.loads(value.value), timestamp=_opt_from_ts(value.timestamp)) class SnapshotProducer: @@ -94,9 +91,9 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def update(self, value: Any, *, timestamp: timedelta | None = None) -> None: + def update(self, value: Any, *, timestamp: Timestamp | None = None) -> None: """Publish a new value. A no-op if unchanged from the previous update.""" - self._inner.update(json.dumps(value), _opt_us(timestamp, "timestamp")) + self._inner.update(json.dumps(value), _opt_ts(timestamp)) def finish(self) -> None: """Finish the track, closing any open group.""" @@ -117,9 +114,9 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def append(self, value: Any, *, timestamp: timedelta | None = None) -> None: + def append(self, value: Any, *, timestamp: Timestamp | None = None) -> None: """Append one record to the log.""" - self._inner.append(json.dumps(value), _opt_us(timestamp, "timestamp")) + self._inner.append(json.dumps(value), _opt_ts(timestamp)) def finish(self) -> None: """Finish the track, closing the group.""" @@ -194,13 +191,13 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def push(self, value: Any, *, timestamp: timedelta | None = None) -> None: + def push(self, value: Any, *, timestamp: Timestamp | None = None) -> None: """Append one record to the back of the window.""" - self._inner.push(json.dumps(value), _opt_us(timestamp, "timestamp")) + self._inner.push(json.dumps(value), _opt_ts(timestamp)) - def pop(self, count: int, *, timestamp: timedelta | None = None) -> None: + def pop(self, count: int, *, timestamp: Timestamp | None = None) -> None: """Drop ``count`` records from the front of the window, clamped to what it holds.""" - self._inner.pop(count, _opt_us(timestamp, "timestamp")) + self._inner.pop(count, _opt_ts(timestamp)) def cut(self) -> None: """Close the open group, so the next edit opens one restating the retained window. @@ -258,7 +255,7 @@ def _window_event(timed: MoqJsonWindowTimed | None) -> Timed | None: value = WindowSkip(range(event.start, event.end)) else: raise TypeError(f"unknown window event: {event!r}") - return Timed(value=value, timestamp=_opt_from_us(timed.timestamp_us)) + return Timed(value=value, timestamp=_opt_from_ts(timed.timestamp)) class WindowConsumer(_Stream[Timed]): diff --git a/py/moq-rs/moq/media.py b/py/moq-rs/moq/media.py index bf06e6e8228..d82b757c691 100644 --- a/py/moq-rs/moq/media.py +++ b/py/moq-rs/moq/media.py @@ -4,7 +4,6 @@ import json from dataclasses import dataclass, field -from datetime import timedelta from typing import Any, cast from moq_ffi import MoqAudio as Audio @@ -54,7 +53,7 @@ from . import subscribe as _subscribe from ._read import End, Gap, _end, _gap -from ._records import Frame, Subscription, _from_us, _subscription +from ._records import Frame, Subscription, Timestamp, _subscription from ._stream import _Stream from .publish import BroadcastProducer, TrackDemand, TrackRequest from .subscribe import BroadcastConsumer @@ -111,12 +110,12 @@ class MediaFrame: """A container-decoded payload, presentation timestamp, and keyframe flag.""" payload: bytes - timestamp: timedelta + timestamp: Timestamp keyframe: bool @staticmethod def _from_ffi(frame: MoqMediaFrame) -> MediaFrame: - return MediaFrame(frame.payload, _from_us(frame.timestamp_us), frame.keyframe) + return MediaFrame(frame.payload, Timestamp._from_ffi(frame.timestamp), frame.keyframe) Read = MediaFrame | Gap | End @@ -129,9 +128,9 @@ class CatalogProducer: def __init__(self, broadcast: BroadcastProducer) -> None: self._inner = MoqMediaCatalogProducer(broadcast._inner) - def now(self) -> timedelta: + def now(self) -> Timestamp: """Read the broadcast clock, fixing it for subsequent media producers.""" - return _from_us(self._inner.now()) + return Timestamp._from_ffi(self._inner.now()) def set_video_properties(self, properties: VideoProperties) -> None: """Replace the video properties shared by every rendition.""" @@ -179,7 +178,7 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this media track has subscribers.""" return TrackDemand(self._inner.demand()) - def write_frame(self, payload: bytes, timestamp: timedelta) -> None: + def write_frame(self, payload: bytes, timestamp: Timestamp) -> None: """Write one encoded frame with a presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) @@ -312,9 +311,9 @@ async def _next(self) -> Read | None: if isinstance(value, MoqMediaRead.FRAME): return MediaFrame._from_ffi(value.frame) if isinstance(value, MoqMediaRead.GAP): - return _gap(value.timestamp_us, value.duration) + return _gap(value.timestamp, value.duration) if isinstance(value, MoqMediaRead.END): - return _end(value.end_us) + return _end(value.end) raise TypeError(f"unknown media read: {value!r}") def cancel(self) -> None: diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 1dd057f7f0b..bb48b38ae2a 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -23,6 +23,7 @@ Frame, Position, Subscription, + Timestamp, TrackInfo, ) @@ -47,7 +48,7 @@ def consume(self) -> GroupConsumer: return GroupConsumer(self._inner.consume()) - def write_frame(self, payload: bytes, timestamp: timedelta | None = None) -> None: + def write_frame(self, payload: bytes, timestamp: Timestamp | None = None) -> None: """Write a frame with its presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) @@ -117,11 +118,11 @@ def create_group(self, sequence: int) -> GroupProducer: """Create a group with an explicit sequence number.""" return GroupProducer(self._inner.create_group(sequence)) - def write_frame(self, payload: bytes, timestamp: timedelta | None = None) -> None: + def write_frame(self, payload: bytes, timestamp: Timestamp | None = None) -> None: """Write a single-frame group with its presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) - def append_datagram(self, payload: bytes, timestamp: timedelta | None = None) -> int: + def append_datagram(self, payload: bytes, timestamp: Timestamp | None = None) -> int: """Send a best-effort datagram and return its sequence number. Payloads are capped at 1200 bytes. Datagram delivery requires a datagram-capable @@ -129,7 +130,7 @@ def append_datagram(self, payload: bytes, timestamp: timedelta | None = None) -> """ return self._inner.append_datagram(Frame(payload, timestamp)._ffi()) - def insert_datagram(self, sequence: int, payload: bytes, timestamp: timedelta | None = None) -> None: + def insert_datagram(self, sequence: int, payload: bytes, timestamp: Timestamp | None = None) -> None: """Send a best-effort datagram at an explicit sequence number. For a caller that allocates its own sequences; :meth:`append_datagram` diff --git a/py/moq-rs/moq/types.py b/py/moq-rs/moq/types.py index 2615ec6453a..ff6dc5dc3dc 100644 --- a/py/moq-rs/moq/types.py +++ b/py/moq-rs/moq/types.py @@ -1,11 +1,9 @@ """Re-export moq-ffi record types without the Moq prefix. -Records the wrapper gives Python defaults or timestamp conversions are owned in `_records` instead. +Records the wrapper gives Python defaults or timestamp conversions, and handles that return a +timestamp, are owned in `_records` instead. """ -from moq_ffi import ( - MoqAnchor as Anchor, -) from moq_ffi import ( MoqAnnounceRoute as AnnounceRoute, ) @@ -42,18 +40,12 @@ from moq_ffi import ( MoqProtocolKind as ProtocolKind, ) -from moq_ffi import ( - MoqRange as Range, -) from moq_ffi import ( MoqRoute as Route, ) from moq_ffi import ( MoqVideoCodec as VideoCodec, ) -from moq_ffi import ( - MoqVideoDecodedFrame as VideoDecodedFrame, -) from moq_ffi import ( MoqVideoEncoderInput as VideoEncoderInput, ) @@ -71,6 +63,7 @@ ) from ._records import ( + Anchor, Backoff, ClientTls, ConnectionStats, @@ -78,8 +71,11 @@ Frame, Grant, QuicConfig, + Range, Subscription, + Timestamp, TrackInfo, + VideoDecodedFrame, WebSocketConfig, ) @@ -107,6 +103,7 @@ "Range", "Route", "Subscription", + "Timestamp", "TrackInfo", "VideoCodec", "VideoEncoderInput", diff --git a/py/moq-rs/moq/video.py b/py/moq-rs/moq/video.py index d96f782461b..2c7c8ad88cd 100644 --- a/py/moq-rs/moq/video.py +++ b/py/moq-rs/moq/video.py @@ -3,8 +3,6 @@ from __future__ import annotations from dataclasses import dataclass -from datetime import timedelta -from typing import Union from moq_ffi import ( MoqVideoConsumer, @@ -19,22 +17,20 @@ from moq_ffi import MoqVideoFrameRate as FrameRate from ._read import End, Gap, _end, _gap -from ._records import _from_us, _to_us +from ._records import Timestamp, VideoDecodedFrame from ._stream import _Stream from .media import CatalogProducer, DecodeStart, Delay, Dimensions, Video from .publish import TrackDemand from .session import Allocator, Reservation from .subscribe import BroadcastConsumer from .types import VideoCodec as Codec -from .types import VideoDecodedFrame from .types import VideoEncoderInput as EncoderInput from .types import VideoEncoderKind as EncoderKind from .types import VideoEncoderOutput as EncoderOutput from .types import VideoGop as Gop from .types import VideoPixelFormat as PixelFormat -# A Union rather than `|`: the generated frame class does not support `|` with other types. -Read = Union[VideoDecodedFrame, Gap, End] +Read = VideoDecodedFrame | Gap | End """One item a :class:`Consumer` reads, in delivery order: a decoded picture, or a break between them.""" @@ -42,24 +38,24 @@ class Frame: """One raw picture in the configured input layout, with its presentation timestamp.""" - timestamp: timedelta + timestamp: Timestamp data: bytes def _ffi(self) -> MoqVideoFrame: - return MoqVideoFrame(timestamp_us=_to_us(self.timestamp, "timestamp"), data=self.data) + return MoqVideoFrame(timestamp=self.timestamp._ffi(), data=self.data) @dataclass(frozen=True) class Packet: """One encoded access unit from an :class:`Encoder`.""" - timestamp: timedelta + timestamp: Timestamp data: bytes keyframe: bool @staticmethod def _from_ffi(value: MoqVideoPacket) -> Packet: - return Packet(timestamp=_from_us(value.timestamp_us), data=value.data, keyframe=value.keyframe) + return Packet(timestamp=Timestamp._from_ffi(value.timestamp), data=value.data, keyframe=value.keyframe) @dataclass(frozen=True) @@ -183,11 +179,11 @@ async def _next(self) -> Read | None: if value is None: return None if isinstance(value, MoqVideoRead.FRAME): - return value.frame + return VideoDecodedFrame(value.frame) if isinstance(value, MoqVideoRead.GAP): - return _gap(value.timestamp_us, value.duration) + return _gap(value.timestamp, value.duration) if isinstance(value, MoqVideoRead.END): - return _end(value.end_us) + return _end(value.end) raise TypeError(f"unknown video read: {value!r}") def cancel(self) -> None: diff --git a/py/moq-rs/tests/test_data_timestamps.py b/py/moq-rs/tests/test_data_timestamps.py index 1f829db647b..4cfe802a8a8 100644 --- a/py/moq-rs/tests/test_data_timestamps.py +++ b/py/moq-rs/tests/test_data_timestamps.py @@ -1,4 +1,4 @@ -"""Data publishers preserve the caller's capture time, including absence.""" +"""Publishers preserve the caller's exact capture time, including absence.""" import asyncio import json @@ -9,12 +9,48 @@ import moq_ffi import pytest +TIMESTAMPS = [None, moq.Timestamp(0, 90_000), moq.Timestamp(1, 90_000)] + + +async def test_raw_timestamps_are_exact(): + """A present zero stays present, and one 90 kHz tick reads back as itself, not the 11 µs it floors to.""" + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("video", moq.TrackInfo(timescale=90_000)) + consumer = track.consume() + for value in [0, 1]: + track.write_frame(b"frame", moq.Timestamp(value, 90_000)) + frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) + assert frame is not None + assert frame.timestamp == moq.Timestamp(value, 90_000) + + untimed = broadcast.publish_track("events", moq.TrackInfo(timescale=None)) + untimed_consumer = untimed.consume() + untimed.write_frame(b"event") + frame = await asyncio.wait_for(untimed_consumer.read_frame(), timeout=5.0) + assert frame is not None + assert frame.timestamp is None + + for invalid in [moq.Timestamp(0, 0), moq.Timestamp(0, 1 << 62), moq.Timestamp(1 << 61, 90_000)]: + with pytest.raises(moq.Error.TimeOverflow): + track.write_frame(b"frame", invalid) + broadcast.close() + + +def test_timedelta_conversions(): + assert moq.Timestamp.from_timedelta(timedelta(seconds=1, microseconds=5)) == moq.Timestamp(1_000_005, 1_000_000) + with pytest.raises(ValueError): + moq.Timestamp.from_timedelta(timedelta(microseconds=-1)) + # Rounded down, like moq-net: half a microsecond and 2/3 of one are both 0, and 11.1 µs is 11 µs. + assert moq.Timestamp(1, 2_000_000).to_timedelta() == timedelta(0) + assert moq.Timestamp(2, 3_000_000).to_timedelta() == timedelta(0) + assert moq.Timestamp(1, 90_000).to_timedelta() == timedelta(microseconds=11) + @pytest.mark.parametrize("mode", ["snapshot", "stream"]) -@pytest.mark.parametrize("timestamp", [None, timedelta(microseconds=123_456)]) -async def test_json_timestamp_round_trip(mode: str, timestamp: timedelta | None): +@pytest.mark.parametrize("timestamp", TIMESTAMPS) +async def test_json_timestamp_round_trip(mode: str, timestamp: moq.Timestamp | None): broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("value", moq.TrackInfo(timescale=None if timestamp is None else 1_000_000)) + track = broadcast.publish_track("value", moq.TrackInfo(timescale=None if timestamp is None else timestamp.scale)) consumer = track.consume() value = {"n": 1} if mode == "snapshot": @@ -35,7 +71,7 @@ async def test_json_timestamp_round_trip(mode: str, timestamp: timedelta | None) def test_catalog_now_uses_a_weak_broadcast_handle(): broadcast = moq.BroadcastProducer() catalog = moq.media.CatalogProducer(broadcast) - assert catalog.now() >= timedelta(0) + assert catalog.now().scale == 1_000_000 broadcast.close() with pytest.raises(moq.Error.Closed): catalog.now() @@ -55,7 +91,7 @@ def test_whole_media_frames_require_the_callers_timestamp(): broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=head) ) with pytest.raises(moq.Error.Codec, match="timestamp"): - producer._inner.write_frame(moq_ffi.MoqFrame(payload=b"opus frame", timestamp_us=None)) + producer._inner.write_frame(moq_ffi.MoqFrame(payload=b"opus frame", timestamp=None)) # Exercise the runtime refusal when a caller omits the required timestamp. with pytest.raises(TypeError): producer.write_frame(b"opus frame") # type: ignore[call-arg] diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index f208690971a..0d66c327bdb 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -12,7 +12,7 @@ import pytest # Every group from the first, rather than only what the live edge still reaches. -FROM_GROUP_0 = [moq.Range(start=cast(moq.Anchor, moq.Anchor.ABSOLUTE(group=0)))] +FROM_GROUP_0 = [moq.Range(start=moq.Anchor.ABSOLUTE(group=0))] async def until_wanted(demand: moq.TrackDemand, wanted: bool = True) -> None: @@ -177,7 +177,7 @@ def test_publish_media_lifecycle(): media = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) - media.write_frame(b"opus frame", timedelta(microseconds=1000)) + media.write_frame(b"opus frame", moq.Timestamp(1000, 1_000_000)) media.finish() broadcast.close() @@ -194,14 +194,14 @@ def test_publish_media_cut_and_seek(): ) for i in range(3): - media.write_frame(b"opus frame", timedelta(microseconds=i * 20_000)) + media.write_frame(b"opus frame", moq.Timestamp(i * 20_000, 1_000_000)) media.cut() # The same boundary, with the next group explicitly numbered. - media.write_frame(b"opus frame", timedelta(microseconds=60_000)) + media.write_frame(b"opus frame", moq.Timestamp(60_000, 1_000_000)) media.seek(42) media.discontinuity() - media.write_frame(b"resumed opus frame", timedelta(microseconds=100_000)) + media.write_frame(b"resumed opus frame", moq.Timestamp(100_000, 1_000_000)) media.finish() broadcast.close() @@ -251,12 +251,12 @@ async def test_local_publish_consume_audio(): media_consumer = await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, audio) payload = b"opus audio payload data" - media.write_frame(payload, timedelta(microseconds=1_000_000)) + media.write_frame(payload, moq.Timestamp(1_000_000, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) assert frame.payload == payload - assert frame.timestamp // timedelta(microseconds=1) == 1_000_000 + assert frame.timestamp == moq.Timestamp(1_000_000, 1_000_000) break break @@ -288,11 +288,11 @@ async def test_video_publish_consume(): media_consumer = await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, video) keyframe = bytes([0x00, 0x00, 0x00, 0x01, 0x65, 0xAA, 0xBB, 0xCC]) - media.write_frame(keyframe, timedelta(microseconds=0)) + media.write_frame(keyframe, moq.Timestamp(0, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) - assert frame.timestamp // timedelta(microseconds=1) == 0 + assert frame.timestamp == moq.Timestamp(0, 1_000_000) assert len(frame.payload) > 0 break @@ -336,12 +336,12 @@ async def test_multiple_frames_ordering(): timestamps = [0, 20_000, 40_000, 60_000, 80_000] for i, ts in enumerate(timestamps): - media.write_frame(f"frame-{i}".encode(), timedelta(microseconds=ts)) + media.write_frame(f"frame-{i}".encode(), moq.Timestamp(ts, 1_000_000)) for i, expected_ts in enumerate(timestamps): async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) - assert frame.timestamp // timedelta(microseconds=1) == expected_ts + assert frame.timestamp == moq.Timestamp(expected_ts, 1_000_000) assert frame.payload == f"frame-{i}".encode() break @@ -503,7 +503,7 @@ async def test_fetch_group_and_serve_dynamic_miss(): consumer = broadcast.consume() cached = track.append_group() - cached.write_frame(b"cached", timedelta(0)) + cached.write_frame(b"cached", moq.Timestamp(0, 1_000_000)) cached.finish() fetched = await consumer.fetch_group("events", 0, moq.FetchGroupOptions(priority=3)) @@ -520,7 +520,7 @@ async def test_fetch_group_and_serve_dynamic_miss(): assert not fill.is_wanted(8) produced = fill.accept(7) - produced.write_frame(b"archive", timedelta(microseconds=140_000)) + produced.write_frame(b"archive", moq.Timestamp(140_000, 1_000_000)) produced.finish() fetched = await asyncio.wait_for(pending, timeout=5.0) @@ -534,15 +534,15 @@ async def test_json_snapshot_roundtrip(): consumer = moq.json.SnapshotConsumer(await broadcast.consume().subscribe_track("status")) for viewers in range(1, 5): - producer.update({"viewers": viewers}, timestamp=timedelta(milliseconds=viewers)) + producer.update({"viewers": viewers}, timestamp=moq.Timestamp(viewers, 1_000)) # Iteration yields every state in order; latest() skips the buffered third. value = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert value == moq.json.Timed({"viewers": 1}, timedelta(milliseconds=1)) + assert value == moq.json.Timed({"viewers": 1}, moq.Timestamp(1_000, 1_000_000)) value = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert value == moq.json.Timed({"viewers": 2}, timedelta(milliseconds=2)) + assert value == moq.json.Timed({"viewers": 2}, moq.Timestamp(2_000, 1_000_000)) value = await asyncio.wait_for(consumer.latest(), timeout=5.0) - assert value == moq.json.Timed({"viewers": 4}, timedelta(milliseconds=4)) + assert value == moq.json.Timed({"viewers": 4}, moq.Timestamp(4_000, 1_000_000)) producer.finish() assert await asyncio.wait_for(consumer.latest(), timeout=5.0) is None @@ -570,18 +570,18 @@ async def test_json_window_roundtrip(): await asyncio.wait_for(until_wanted(demand), timeout=5.0) for n in range(3): - producer.push({"n": n}, timestamp=timedelta(milliseconds=n)) - producer.pop(2, timestamp=timedelta(milliseconds=3)) + producer.push({"n": n}, timestamp=moq.Timestamp(n, 1_000)) + producer.pop(2, timestamp=moq.Timestamp(3, 1_000)) for n in range(3): event = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert event == moq.json.Timed(moq.json.WindowPush(n, {"n": n}), timedelta(milliseconds=n)) + assert event == moq.json.Timed(moq.json.WindowPush(n, {"n": n}), moq.Timestamp(n * 1_000, 1_000_000)) event = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert event == moq.json.Timed(moq.json.WindowPop(range(0, 2)), timedelta(milliseconds=3)) + assert event == moq.json.Timed(moq.json.WindowPop(range(0, 2)), moq.Timestamp(3_000, 1_000_000)) producer.finish() with pytest.raises(moq.Error.Closed): - producer.push({"n": 3}, timestamp=timedelta(milliseconds=4)) + producer.push({"n": 3}, timestamp=moq.Timestamp(4, 1_000)) assert [event async for event in consumer] == [] @@ -755,12 +755,12 @@ async def test_dynamic_track_request_can_publish_media(): assert audio.channel_count == 2 payload = b"dynamic opus frame" - media.write_frame(payload, timedelta(microseconds=20_000)) + media.write_frame(payload, moq.Timestamp(20_000, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) assert frame.payload == payload - assert frame.timestamp // timedelta(microseconds=1) == 20_000 + assert frame.timestamp == moq.Timestamp(20_000, 1_000_000) break media.finish() @@ -786,12 +786,12 @@ async def test_dynamic_broadcast_request(): broadcast = await asyncio.wait_for(requesting, timeout=5.0) track_consumer = await broadcast.subscribe_track("status") payload = b"served dynamically" - track.write_frame(payload, timedelta(microseconds=20_000)) + track.write_frame(payload, moq.Timestamp(20_000, 1_000_000)) frame = await asyncio.wait_for(track_consumer.read_frame(), timeout=5.0) assert frame is not None assert frame.payload == payload - assert frame.timestamp == timedelta(microseconds=20_000) + assert frame.timestamp == moq.Timestamp(20_000, 1_000_000) track.finish() served.broadcast.close() @@ -834,7 +834,7 @@ def test_raw_group_write_multiple_frames(): group = track.append_group() for i in range(10): - group.write_frame(f"frame-{i}".encode(), timedelta(microseconds=i)) + group.write_frame(f"frame-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() @@ -911,9 +911,9 @@ def test_raw_parallel_groups(): assert g0.sequence == 0 assert g1.sequence == 1 - g0.write_frame(b"a0", timedelta(0)) - g1.write_frame(b"b0", timedelta(0)) - g0.write_frame(b"a1", timedelta(microseconds=1)) + g0.write_frame(b"a0", moq.Timestamp(0, 1_000_000)) + g1.write_frame(b"b0", moq.Timestamp(0, 1_000_000)) + g0.write_frame(b"a1", moq.Timestamp(1, 1_000_000)) g0.finish() g1.finish() @@ -960,7 +960,7 @@ async def test_container_consumer_default_latency_and_context_manager(): # No container argument, no explicit latency. payload = b"opus audio payload data" - media.write_frame(payload, timedelta(microseconds=1_000_000)) + media.write_frame(payload, moq.Timestamp(1_000_000, 1_000_000)) async with await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, audio) as media_consumer: async for frame in media_consumer: @@ -1052,13 +1052,13 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): track = broadcast.publish_track("backlog", moq.TrackInfo(timescale=1_000_000)) for ms in range(3): group = track.append_group() - group.write_frame(b"x", timedelta(milliseconds=ms)) + group.write_frame(b"x", moq.Timestamp(ms, 1_000)) group.finish() consumer = track.consume( moq.Subscription( max_delay=timedelta(seconds=10), - ranges=[moq.Range(start=cast(moq.Anchor, moq.Anchor.RELATIVE(groups=2)))], + ranges=[moq.Range(start=moq.Anchor.RELATIVE(groups=2))], order=moq.Order.ASCENDING, ) ) @@ -1070,6 +1070,28 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): assert sequences == [0, 1, 2] +async def test_time_anchor_starts_at_the_group_containing_it(): + """A time anchor takes a wrapper Timestamp and starts at the group containing that time.""" + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("timed", moq.TrackInfo(timescale=1_000)) + for second in range(3): + group = track.append_group() + group.write_frame(b"x", moq.Timestamp(second, 1)) + group.finish() + + start = moq.Anchor.TIME(timestamp=moq.Timestamp(1_500, 1_000)) + consumer = track.consume( + moq.Subscription( + max_delay=timedelta(seconds=10), + ranges=[moq.Range(start=start)], + order=moq.Order.ASCENDING, + ) + ) + group = await asyncio.wait_for(consumer.recv_group(), timeout=5.0) + assert group is not None + assert group.sequence == 1 + + async def test_raw_group_producer_consume_direct(): """Consume a single group directly from the group producer.""" broadcast = moq.BroadcastProducer() @@ -1120,7 +1142,7 @@ async def test_raw_group_sequence(): for i in range(3): group = raw.append_group() sent_sequences.append(group.sequence) - group.write_frame(f"msg-{i}".encode(), timedelta(microseconds=i)) + group.write_frame(f"msg-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() received_sequences = [] @@ -1199,23 +1221,23 @@ async def test_container_group_decodes_arrival_order(): consumer = await broadcast.consume().subscribe_track("audio") first = track.append_group() - first.write_frame(_legacy(1_000_000, b"a"), timedelta(milliseconds=1)) + first.write_frame(_legacy(1_000_000, b"a"), moq.Timestamp(1, 1_000)) first_media = await _recv_media(consumer) frame = await asyncio.wait_for(anext(first_media), timeout=5.0) - assert (frame.payload, frame.timestamp, frame.keyframe) == (b"a", timedelta(seconds=1), True) + assert (frame.payload, frame.timestamp, frame.keyframe) == (b"a", moq.Timestamp(1_000_000, 1_000_000), True) # A newer group lands while the first is stalled mid-way. second = track.append_group() - second.write_frame(_legacy(1_040_000, b"c"), timedelta(milliseconds=2)) + second.write_frame(_legacy(1_040_000, b"c"), moq.Timestamp(2, 1_000)) second_media = await _recv_media(consumer) assert second_media.sequence == 1 frame = await asyncio.wait_for(anext(second_media), timeout=5.0) - assert (frame.payload, frame.timestamp) == (b"c", timedelta(microseconds=1_040_000)) + assert (frame.payload, frame.timestamp) == (b"c", moq.Timestamp(1_040_000, 1_000_000)) # The stalled group resumes and is still delivered. - first.write_frame(_legacy(1_020_000, b"b"), timedelta(milliseconds=3)) + first.write_frame(_legacy(1_020_000, b"b"), moq.Timestamp(3, 1_000)) frame = await asyncio.wait_for(anext(first_media), timeout=5.0) - assert (frame.payload, frame.timestamp, frame.keyframe) == (b"b", timedelta(microseconds=1_020_000), False) + assert (frame.payload, frame.timestamp, frame.keyframe) == (b"b", moq.Timestamp(1_020_000, 1_000_000), False) first.finish() second.finish() @@ -1230,20 +1252,20 @@ async def test_container_group_takes_over_an_unread_group(): consumer = await broadcast.consume().subscribe_track("audio") group = track.append_group() - group.write_frame(_legacy(1_000_000, b"a"), timedelta(milliseconds=1)) + group.write_frame(_legacy(1_000_000, b"a"), moq.Timestamp(1, 1_000)) raw = await _recv_raw(consumer) assert await raw.read_frame() is not None with pytest.raises(moq.Error.AlreadyCommitted): moq.media.GroupConsumer(raw, _LEGACY) group = track.append_group() - group.write_frame(_legacy(1_020_000, b"b"), timedelta(milliseconds=2)) + group.write_frame(_legacy(1_020_000, b"b"), moq.Timestamp(2, 1_000)) raw = await _recv_raw(consumer) media = moq.media.GroupConsumer(raw, _LEGACY) with pytest.raises(moq.Error.Cancelled): await raw.read_frame() frame = await asyncio.wait_for(anext(media), timeout=5.0) - assert frame.timestamp == timedelta(microseconds=1_020_000) + assert frame.timestamp == moq.Timestamp(1_020_000, 1_000_000) async def test_container_group_fails_loudly(): @@ -1254,7 +1276,7 @@ async def test_container_group_fails_loudly(): group = track.append_group() # A truncated varint timestamp: the 2-byte form with only its first byte. - group.write_frame(b"\x40", timedelta(milliseconds=1)) + group.write_frame(b"\x40", moq.Timestamp(1, 1_000)) raw = await _recv_raw(consumer) with pytest.raises(moq.Error.Codec): moq.media.GroupConsumer(raw, cast(moq.media.Container, moq.media.Container.CMAF(init=b""))) @@ -1317,21 +1339,21 @@ async def test_raw_read_frame_preserves_timestamp(): track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) consumer = track.consume() - track.write_frame(b"ready", timedelta(microseconds=12_345)) + track.write_frame(b"ready", moq.Timestamp(12_345, 1_000_000)) frame = await consumer.read_frame() assert frame is not None assert frame.payload == b"ready" - assert frame.timestamp == timedelta(microseconds=12_345) + assert frame.timestamp == moq.Timestamp(12_345, 1_000_000) group = track.append_group() group_consumer = group.consume() - group.write_frame(b"group", timedelta(microseconds=23_456)) + group.write_frame(b"group", moq.Timestamp(23_456, 1_000_000)) group.finish() frame = await group_consumer.read_frame() assert frame is not None assert frame.payload == b"group" - assert frame.timestamp == timedelta(microseconds=23_456) + assert frame.timestamp == moq.Timestamp(23_456, 1_000_000) async def test_read_frame_skips_remaining_frames_in_group(): @@ -1382,11 +1404,11 @@ async def test_read_frame_skips_empty_group_on_open_track(): await asyncio.sleep(0.05) assert not read.done(), "empty group must not end an open track" - track.write_frame(b"after-empty", timedelta(microseconds=1_000)) + track.write_frame(b"after-empty", moq.Timestamp(1_000, 1_000_000)) frame = await asyncio.wait_for(read, timeout=5.0) assert frame is not None assert frame.payload == b"after-empty" - assert frame.timestamp == timedelta(microseconds=1_000) + assert frame.timestamp == moq.Timestamp(1_000, 1_000_000) async def test_read_frame_skips_empty_then_populated_groups(): @@ -1397,12 +1419,12 @@ async def test_read_frame_skips_empty_then_populated_groups(): track.append_group().finish() track.append_group().finish() - track.write_frame(b"populated", timedelta(microseconds=2_000)) + track.write_frame(b"populated", moq.Timestamp(2_000, 1_000_000)) frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) assert frame is not None assert frame.payload == b"populated" - assert frame.timestamp == timedelta(microseconds=2_000) + assert frame.timestamp == moq.Timestamp(2_000, 1_000_000) async def test_read_frame_keeps_group_across_cancelled_call(): @@ -1419,14 +1441,14 @@ async def test_read_frame_keeps_group_across_cancelled_call(): with pytest.raises(asyncio.CancelledError): await read - group.write_frame(b"kept", timedelta(microseconds=3_000)) + group.write_frame(b"kept", moq.Timestamp(3_000, 1_000_000)) group.finish() track.finish() frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) assert frame is not None assert frame.payload == b"kept" - assert frame.timestamp == timedelta(microseconds=3_000) + assert frame.timestamp == moq.Timestamp(3_000, 1_000_000) assert await asyncio.wait_for(consumer.read_frame(), timeout=5.0) is None @@ -1488,7 +1510,7 @@ def test_encode_audio_with_opus_object(): del output del codec # One 20 ms Opus frame of silence at 48 kHz mono. - producer.write(moq.audio.Frame(timestamp=timedelta(0), data=bytes(960 * 4))) + producer.write(moq.audio.Frame(timestamp=moq.Timestamp(0, 1_000_000), data=bytes(960 * 4))) assert producer.demand().name == "mic" producer.finish() broadcast.close() @@ -1525,7 +1547,7 @@ def output(delay: timedelta | None) -> moq.audio.DecoderOutput: # Two 20 ms Opus frames of silence at 48 kHz mono. for i in range(2): - audio.write(moq.audio.Frame(timestamp=timedelta(milliseconds=20 * i), data=bytes(960 * 4))) + audio.write(moq.audio.Frame(timestamp=moq.Timestamp(20 * i, 1_000), data=bytes(960 * 4))) assert isinstance(await asyncio.wait_for(anext(fixed), timeout=5.0), moq.audio.Frame) assert isinstance(await asyncio.wait_for(anext(estimated), timeout=5.0), moq.audio.Frame) @@ -1564,7 +1586,7 @@ async def test_decode_video_frame(): rgba = bytes([0x80]) * (320 * 240 * 4) video.cut() for i in range(10): - video.write(moq.video.Frame(timestamp=timedelta(microseconds=i * 33_333), data=rgba)) + video.write(moq.video.Frame(timestamp=moq.Timestamp(i * 33_333, 1_000_000), data=rgba)) consumer = origin.consume() broadcast_consumer = await asyncio.wait_for(consumer.request("video-decode-frame"), timeout=5.0) @@ -1576,11 +1598,12 @@ async def test_decode_video_frame(): # Keep the encoder fed so the decoder sees frames after it joined. for i in range(10, 40): - video.write(moq.video.Frame(timestamp=timedelta(microseconds=i * 33_333), data=rgba)) + video.write(moq.video.Frame(timestamp=moq.Timestamp(i * 33_333, 1_000_000), data=rgba)) frame = await asyncio.wait_for(anext(decoder), timeout=5.0) decoder.cancel() assert isinstance(frame, moq.VideoDecodedFrame) + assert frame.timestamp().scale == 1_000_000 i420 = frame.pixels(moq.VideoPixelFormat.I420) diff --git a/py/moq-rs/tests/test_media_reads.py b/py/moq-rs/tests/test_media_reads.py index 9e583c2d6f0..1199a68904e 100644 --- a/py/moq-rs/tests/test_media_reads.py +++ b/py/moq-rs/tests/test_media_reads.py @@ -3,18 +3,20 @@ from datetime import timedelta from typing import Any, cast -from moq import media -from moq_ffi import MoqMediaFrame, MoqMediaRead +from moq import Timestamp, media +from moq_ffi import MoqMediaFrame, MoqMediaRead, MoqTimestamp async def test_tagged_media_reads_preserve_frames_breaks_and_eof(): payload = b"encoded packet" + first = MoqTimestamp(value=11_111, scale=90_000) + end = MoqTimestamp(value=18_212, scale=90_000) records = iter( [ - MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=payload, timestamp_us=123_456, keyframe=True)), - MoqMediaRead.GAP(timestamp_us=123_456, duration=timedelta(microseconds=78_901)), - MoqMediaRead.END(end_us=202_357), - MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=b"resumed", timestamp_us=202_357, keyframe=False)), + MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=payload, timestamp=first, keyframe=True)), + MoqMediaRead.GAP(timestamp=first, duration=timedelta(microseconds=78_901)), + MoqMediaRead.END(end=end), + MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=b"resumed", timestamp=end, keyframe=False)), None, ] ) @@ -24,8 +26,8 @@ async def next(self): return next(records) reader = media.TrackConsumer(cast(Any, Inner())) - assert await reader._next() == media.MediaFrame(payload, timedelta(microseconds=123_456), True) - assert await reader._next() == media.Gap(timedelta(microseconds=123_456), timedelta(microseconds=78_901)) - assert await reader._next() == media.End(timedelta(microseconds=202_357)) - assert await reader._next() == media.MediaFrame(b"resumed", timedelta(microseconds=202_357), False) + assert await reader._next() == media.MediaFrame(payload, Timestamp(11_111, 90_000), True) + assert await reader._next() == media.Gap(Timestamp(11_111, 90_000), timedelta(microseconds=78_901)) + assert await reader._next() == media.End(Timestamp(18_212, 90_000)) + assert await reader._next() == media.MediaFrame(b"resumed", Timestamp(18_212, 90_000), False) assert await reader._next() is None diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index c8f3f7f664c..11297357e69 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -82,12 +82,12 @@ async def accept_loop() -> None: media_consumer = await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, audio) payload = b"hello over the wire" - media.write_frame(payload, timedelta(microseconds=1_000_000)) + media.write_frame(payload, moq.Timestamp(1_000_000, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) assert frame.payload == payload - assert frame.timestamp // timedelta(microseconds=1) == 1_000_000 + assert frame.timestamp == moq.Timestamp(1_000_000, 1_000_000) break break diff --git a/quest/m1/README.md b/quest/m1/README.md index 577c6cc0b56..978ec2bf2a2 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -143,7 +143,6 @@ per-frame CPU growth since #5926. - [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [moq-c at parity](/quest/m1/c/README.md) - the hand-written `moq-c` ships at the cut with every m1 binding feature moq-ffi gains -- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds - [Bindings see a moq-transport run end as an end](/quest/m1/ffi-ietf-run-end.md) - an IETF publisher ending its run reaches moq-ffi consumers as an end, not `Internal` - [Byte-stream renditions form a ladder](/quest/m1/stream-ladder.md) - moq-ffi stream producers link as `lower` and disable unfundable rungs like frame producers - [A broadcast stamps everything from one clock](/quest/m1/broadcast-clock.md) - catalog, MSF, and HLS record groups are stamped from the broadcast's clock, never the ambient one diff --git a/quest/m1/binding-timestamps.md b/quest/m1/binding-timestamps.md deleted file mode 100644 index 65a84f2c3aa..00000000000 --- a/quest/m1/binding-timestamps.md +++ /dev/null @@ -1,73 +0,0 @@ -# [L] Exact timestamps in every binding - -## Goal - -Every binding (moq-ffi, moq-c, cpp and cpp/obs, and the py, swift, kt, go and -dart wrappers) carries media timestamps as an exact `{value, scale}` record -mirroring `moq_net::Timestamp`, with untimed as absent. It replaces the lossy -microsecond fields on frames, datagrams, media and audio frames, producer -arguments, and the JSON data values (`MoqJsonValue`, `moq_json_value`, and each -wrapper's `Timed`). - -The Rust core and `@moq/net` already carry exact timestamps. Wire: none. -Public API: breaking in every binding. - -## Plan - -Today every binding speaks microseconds: moq-ffi `timestamp_us: Option` -(about 160 sites in 9 files: `MoqFrame`, `MoqDatagram`, `MoqMediaFrame`, audio -frames, json/flate producer `update`/`append`, media `flush`, the -subscription start `MoqAnchor::Time`), moq-c `timestamp_us` plus -`timestamp_present` pairs (about 140 sites in 6 files, plus -`moq_anchor.timestamp_us` read as `MOQ_ANCHOR_TIME`), and -each wrapper's native type (Python `timedelta`, Go `*time.Duration`, Swift -`UInt64`, Kotlin `Duration`, Dart `int`, C++ `std::optional`, OBS -microseconds). Reads floor through `as_micros()`, so any scale that does not -divide a microsecond loses: a 90 kHz tick reads as 11 µs, and republishing it -onto a 90 kHz track floors again to tick 0. - -Decided with the maintainer on 2026-10-18: - -- **Scope is the bindings only.** The core and JS types stay as they are. -- **m1**, beside data consumer timestamps. -- **#5677 shipped** the data-value timestamps with the interim microsecond - fields; this quest converts every site at once, `MoqJsonValue` included. -- **Shape mirrors the core:** one `{value, scale}` per value, `value` bounded - as `Timestamp::new` bounds it (`2^61 - 1` since - [#6168](https://github.com/moq-dev/moq/pull/6168), decided 2026-10-22) - and `scale` non-zero and at most `2^62 - 1`, matching `Timescale::new`. The FFI boundary refuses anything else with - an error. Rejected: raw ticks at the track scale beside - `MoqTrackInfo.timescale`, because a producer argument needs its own scale - and per-value records match the core and JS. -- **Names:** UniFFI record `MoqTimestamp`, C `moq_timestamp`, wrappers - `Timestamp`. -- **C untimed is a nullable pointer:** `const moq_timestamp *`, `NULL` for - untimed, in arguments and callback structs. No sentinel scale and no - `_present` flag; the existing `timestamp_present` pairs go. -- **Wrappers expose the record plus duration helpers** to and from the - language's duration type (`timedelta`, `Duration`, `time.Duration`, ...). - From a duration is exact at the duration's own scale. To a duration rounds - to nearest and says so in its doc; the record itself stays exact. -- **One PR across every binding**, per the cross-package sync table, so each - binding breaks once. No shim: the microsecond fields are removed, not kept - beside the record. The Impact bullet says how to migrate each package, and `doc/lib/*` - and `doc/bin/obs.md` update in the same PR. - -Verification: round-trip a 90 kHz tick, a present zero, and untimed through -moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0, an -out-of-range scale, and an out-of-range value; `just test interop --all`. - -Decided 2026-10-25 (maintainer), reversing the 2026-10-20 decision to wait -on the generated C package: the hand-written `moq-c` ships at this cut with -parity to moq-ffi for every m1 binding feature, so the moq-c half lands -there, and the generated C line follows after the cut. - -Decided 2026-10-27 (maintainer): producer arguments keep an optional -timestamp until the cut, so producers may still write untimed frames. Reads -keep "untimed as absent" until then too. At the cut -[time addressing](/quest/m1/time-addressing/README.md) makes every track -timed, and [bindings by start](/quest/m1/time-addressing/bindings.md) drops -that `Option` from reads only. - -Wall and monotonic times stay `kio::clock::Wall` and `kio::clock::Instant`, not -media timestamps; keep the types distinct. diff --git a/quest/m1/time-addressing/bindings.md b/quest/m1/time-addressing/bindings.md index 67efa3eef4c..e86a0684aa2 100644 --- a/quest/m1/time-addressing/bindings.md +++ b/quest/m1/time-addressing/bindings.md @@ -9,8 +9,7 @@ failover, with each `doc/lib` page and the PR's Impact section saying how to mig ## Plan Follow the cross-package sync table from `rs/moq-ffi` outward. Timestamps -already cross the bindings as `{value, scale}` -([exact timestamps](/quest/m1/binding-timestamps.md)), so a start reuses that +already cross the bindings as `{value, scale}`, so a start reuses that type. Decided 2026-10-27 (maintainer): every track is timed after the cut, so reads drop the `Option` that exact timestamps keeps for untimed. Only reads drop it here; producer arguments keep their optional timestamp. @@ -20,4 +19,3 @@ Public API: breaking in every binding. Wire: none. ## Required - [Rust groups by start](/quest/m1/time-addressing/model.md) - the API these wrap -- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - the timestamp type a start uses diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index b295f9c5855..bf97b97f2b8 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -80,11 +80,11 @@ int32_t moq_publish_container(uint32_t broadcast, const moq_container_init *conf int32_t moq_publish_container_write(uint32_t container, const uint8_t *payload, uintptr_t payload_size); int32_t moq_publish_container_finish(uint32_t container); int32_t moq_publish_media_finish(uint32_t media); -int32_t moq_publish_media_frame(uint32_t media, const uint8_t *payload, uintptr_t payload_size, uint64_t timestamp_us); +int32_t moq_publish_media_frame(uint32_t media, const uint8_t *payload, uintptr_t payload_size, moq_timestamp timestamp); int32_t moq_publish_track(uint32_t broadcast, const char *name, uintptr_t name_len, const moq_track_info *info); int32_t moq_publish_track_group(uint32_t track); -int32_t moq_publish_track_frame(uint32_t track, const uint8_t *payload, uintptr_t payload_size, uint64_t timestamp_us); -int32_t moq_publish_group_frame(uint32_t group, const uint8_t *payload, uintptr_t payload_size, uint64_t timestamp_us); +int32_t moq_publish_track_frame(uint32_t track, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); +int32_t moq_publish_group_frame(uint32_t group, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); int32_t moq_publish_group_finish(uint32_t group); int32_t moq_publish_track_finish(uint32_t track); @@ -143,8 +143,9 @@ int32_t moq_consume_track_frame_free(uint32_t frame); int32_t moq_consume_track_cancel(uint32_t track); ``` -Raw track frames use the same `moq_frame` record as media frames. Use -`moq_publish_track_frame` or `moq_publish_group_frame` to provide microsecond -presentation timestamps; `moq_consume_track_frame` returns that timestamp in -`moq_frame.timestamp_us`. moq-c creates raw tracks with a microsecond -timescale, matching the C ABI's timestamp units. +Raw track frames use the same `moq_frame` record as media frames. Timestamps +are exact `moq_timestamp` records, `value` units at `scale` units per second. +`moq_publish_track_frame` and `moq_publish_group_frame` convert theirs to the +track's timescale, a microsecond one unless `moq_track_info.timescale` sets +another, and `moq_consume_track_frame` points `moq_frame.timestamp` at the +timestamp read, valid until the frame is freed, or NULL on an untimed track. diff --git a/rs/moq-c/c-tests/audio-decode-output.c b/rs/moq-c/c-tests/audio-decode-output.c index 377916abfaa..140af5e753a 100644 --- a/rs/moq-c/c-tests/audio-decode-output.c +++ b/rs/moq-c/c-tests/audio-decode-output.c @@ -51,7 +51,8 @@ static void on_catalog(void *data, int32_t id) { } static void check_frame(Context *c, const moq_audio_frame *frame) { - CHECK(frame->timestamp_us == 123000 + c->frames * 1000000 / 48000); + CHECK(frame->timestamp.scale == 1000000); + CHECK(frame->timestamp.value == 123000 + c->frames * 1000000 / 48000); size_t bytes = c->format == MOQ_AUDIO_SAMPLE_FORMAT_S16 ? 2 : 4; CHECK(frame->data_size % (bytes * c->channels) == 0); size_t count = frame->data_size / (bytes * c->channels); @@ -114,7 +115,7 @@ int main(void) { CHECK(producer > 0); float pcm[960 * 2]; for (size_t sample = 0; sample < 960; sample++) { pcm[sample * 2] = 0.25f; pcm[sample * 2 + 1] = -0.5f; } - moq_audio_frame frame = {123000, (const uint8_t *)pcm, sizeof(pcm)}; + moq_audio_frame frame = {{123000, 1000000}, (const uint8_t *)pcm, sizeof(pcm)}; CHECK(moq_encode_audio_frame((uint32_t)producer, &frame) == 0); CHECK(moq_encode_audio_finish((uint32_t)producer) == 0); diff --git a/rs/moq-c/c-tests/decode-output.c b/rs/moq-c/c-tests/decode-output.c index 0ac2272e112..42f998cc526 100644 --- a/rs/moq-c/c-tests/decode-output.c +++ b/rs/moq-c/c-tests/decode-output.c @@ -187,7 +187,7 @@ static uint64_t next_ts; static void publish_frames(int32_t producer, int count) { for (int i = 0; i < count; i++) { - moq_video_encoder_frame frame = {next_ts, gray_rgba, sizeof(gray_rgba)}; + moq_video_encoder_frame frame = {{next_ts, 1000000}, gray_rgba, sizeof(gray_rgba)}; next_ts += 33333; int32_t rc = moq_encode_video_frame((uint32_t)producer, &frame); if (rc < 0) fail("error: moq_encode_video_frame failed: %d (%s)\n", rc, moq_error()); diff --git a/rs/moq-c/c-tests/timestamps.c b/rs/moq-c/c-tests/timestamps.c new file mode 100644 index 00000000000..9cc7185e86b --- /dev/null +++ b/rs/moq-c/c-tests/timestamps.c @@ -0,0 +1,159 @@ +// Exact timestamps across the installed C ABI: a 90 kHz tick and a present zero +// read back unchanged from raw frames and datagrams, a JSON value carries its +// frame's timestamp, and a write refuses an out-of-range timestamp or an +// untimed frame on a timed track. moq-c only creates timed tracks, so the +// untimed read path is covered by the Rust tests. +#include + +#include +#include +#include +#include +#include +#include +#include + +#define CHECK(expr) do { if (!(expr)) { \ + fprintf(stderr, "%s:%d: %s (%s)\n", __FILE__, __LINE__, #expr, moq_error()); \ + abort(); \ +} } while (0) + +// Wait up to 10 seconds for `cond`, evaluated under the context lock. +#define WAIT_FOR(c, cond) do { \ + struct timespec deadline; \ + CHECK(clock_gettime(CLOCK_REALTIME, &deadline) == 0); \ + deadline.tv_sec += 10; \ + pthread_mutex_lock(&(c)->mutex); \ + while (!(cond)) CHECK(pthread_cond_timedwait(&(c)->changed, &(c)->mutex, &deadline) == 0); \ + pthread_mutex_unlock(&(c)->mutex); \ +} while (0) + +typedef struct { + pthread_mutex_t mutex; + pthread_cond_t changed; + int32_t broadcast, frames[2], datagram, value; + size_t frame_count; + int request_done, frames_done, datagrams_done, values_done; +} Context; + +// Record a delivered id in `slot`, or the terminal status in `done`. +static void deliver(Context *c, int32_t id, int32_t *slot, int *done) { + pthread_mutex_lock(&c->mutex); + if (id > 0) *slot = id; + else { CHECK(id == 0); *done = 1; } + pthread_cond_broadcast(&c->changed); + pthread_mutex_unlock(&c->mutex); +} + +static void on_broadcast(void *data, int32_t id) { + Context *c = data; + deliver(c, id, &c->broadcast, &c->request_done); +} + +static void on_frame(void *data, int32_t id) { + Context *c = data; + pthread_mutex_lock(&c->mutex); + if (id > 0) { CHECK(c->frame_count < 2); c->frames[c->frame_count++] = id; } + else { CHECK(id == 0); c->frames_done = 1; } + pthread_cond_broadcast(&c->changed); + pthread_mutex_unlock(&c->mutex); +} + +static void on_datagram(void *data, int32_t id) { + Context *c = data; + deliver(c, id, &c->datagram, &c->datagrams_done); +} + +static void on_value(void *data, int32_t id) { + Context *c = data; + deliver(c, id, &c->value, &c->values_done); +} + +static bool same(const moq_timestamp *got, moq_timestamp want) { + return got != NULL && got->value == want.value && got->scale == want.scale; +} + +int main(void) { + Context c = {.mutex = PTHREAD_MUTEX_INITIALIZER, .changed = PTHREAD_COND_INITIALIZER}; + int32_t origin = moq_origin_create(); + CHECK(origin > 0); + const char *path = "timestamps"; + uint32_t broadcast = 0; + int32_t publication = moq_origin_create_broadcast((uint32_t)origin, path, strlen(path), &broadcast); + CHECK(publication > 0); + CHECK(moq_publication_announce((uint32_t)publication, NULL) == 0); + CHECK(moq_publication_free((uint32_t)publication) == 0); + moq_track_info info = {0}; + info.timescale = 90000; + info.timescale_present = true; + int32_t track = moq_publish_track((uint32_t)broadcast, "ticks", 5, &info); + CHECK(track > 0); + int32_t json = moq_publish_json_stream((uint32_t)broadcast, "json", 4); + CHECK(json > 0); + + const uint8_t payload[] = {1, 2, 3}; + const char *doc = "{\"n\":1}"; + const moq_timestamp invalid[] = {{0, 0}, {0, 1ull << 62}, {1ull << 61, 1000000}}; + for (size_t i = 0; i < sizeof(invalid) / sizeof(invalid[0]); i++) { + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &invalid[i]) == + MOQ_ERROR_TIMESTAMP_OVERFLOW); + CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc), &invalid[i]) == + MOQ_ERROR_TIMESTAMP_OVERFLOW); + } + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), NULL) == MOQ_ERROR_MOQ); + + CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), on_broadcast, &c) > 0); + WAIT_FOR(&c, c.broadcast); + int32_t frames = moq_consume_track((uint32_t)c.broadcast, "ticks", 5, NULL, on_frame, &c); + CHECK(frames > 0); + int32_t datagrams = moq_consume_datagrams((uint32_t)c.broadcast, "ticks", 5, on_datagram, &c); + CHECK(datagrams > 0); + int32_t values = moq_consume_json_stream((uint32_t)c.broadcast, "json", 4, on_value, &c); + CHECK(values > 0); + + // One group at a time, so the default subscription never skips the older one, and in + // time order, since a group may not start before the one preceding it. + const moq_timestamp zero = {0, 90000}, tick = {1, 90000}; + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &zero) == 0); + WAIT_FOR(&c, c.frame_count == 1); + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &tick) == 0); + WAIT_FOR(&c, c.frame_count == 2); + CHECK(moq_publish_track_datagram((uint32_t)track, payload, sizeof(payload), &tick, NULL) == 0); + WAIT_FOR(&c, c.datagram); + // JSON tracks moq-c creates count milliseconds. + const moq_timestamp stamped = {1500, 1000}; + CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc), &stamped) == 0); + WAIT_FOR(&c, c.value); + + // Each timestamp points into its own read, so both stay intact until freed. + moq_frame first, second; + CHECK(moq_consume_track_frame((uint32_t)c.frames[0], &first) == 0); + CHECK(moq_consume_track_frame((uint32_t)c.frames[1], &second) == 0); + CHECK(same(first.timestamp, zero)); + CHECK(same(second.timestamp, tick)); + CHECK(moq_consume_track_frame_free((uint32_t)c.frames[0]) == 0); + CHECK(moq_consume_track_frame_free((uint32_t)c.frames[1]) == 0); + + moq_datagram datagram; + CHECK(moq_consume_datagram((uint32_t)c.datagram, &datagram) == 0); + CHECK(same(datagram.timestamp, tick)); + CHECK(moq_consume_datagram_free((uint32_t)c.datagram) == 0); + + moq_json_value value; + CHECK(moq_consume_json_value((uint32_t)c.value, &value) == 0); + CHECK(same(value.timestamp, stamped)); + CHECK(moq_consume_json_value_free((uint32_t)c.value) == 0); + + CHECK(moq_consume_track_cancel((uint32_t)frames) == 0); + CHECK(moq_consume_datagrams_cancel((uint32_t)datagrams) == 0); + CHECK(moq_consume_json_cancel((uint32_t)values) == 0); + WAIT_FOR(&c, c.frames_done && c.datagrams_done && c.values_done); + CHECK(moq_consume_close((uint32_t)c.broadcast) == 0); + CHECK(moq_publish_json_stream_finish((uint32_t)json) == 0); + CHECK(moq_publish_track_finish((uint32_t)track) == 0); + CHECK(moq_publish_close((uint32_t)broadcast) == 0); + CHECK(moq_origin_close((uint32_t)origin) == 0); + WAIT_FOR(&c, c.request_done); + fprintf(stderr, "C exact timestamps passed\n"); + return 0; +} diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 925255b262d..f75dc024e8b 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -15,8 +15,7 @@ use tracing::Level; #[expect(non_camel_case_types, reason = "C ABI type names match moq.h")] #[derive(Clone, Copy, Debug)] pub enum moq_container_kind { - /// A QUIC varint timestamp prefix followed by the raw codec payload. - /// Timestamps are in microseconds. + /// A QUIC varint timestamp prefix in microseconds followed by the raw codec payload. MOQ_CONTAINER_KIND_LEGACY = 0, /// Fragmented MP4: each frame is a complete moof+mdat fragment, described by /// the init segment in `moq_container::init`. @@ -503,6 +502,37 @@ pub struct moq_json_snapshot_config { pub deltas: bool, } +/// An exact media timestamp: `value` units at `scale` units per second. +/// +/// Reads carry the scale the publisher wrote, so a tick such as 90 kHz survives a read and +/// republish exactly. A write with a zero scale, a scale above `2^62 - 1`, or a value above +/// `2^61 - 1` fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +#[repr(C)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct moq_timestamp { + /// The time in `scale` units, at most `2^61 - 1`. + pub value: u64, + /// Units per second, non-zero and at most `2^62 - 1`. + pub scale: u64, +} + +impl From for moq_timestamp { + fn from(timestamp: moq_net::Timestamp) -> Self { + Self { + value: timestamp.value(), + scale: timestamp.scale().as_u64(), + } + } +} + +impl TryFrom for moq_net::Timestamp { + type Error = moq_net::TimeOverflow; + + fn try_from(timestamp: moq_timestamp) -> Result { + Self::from_scale(timestamp.value, timestamp.scale) + } +} + /// Options for a JSON window producer (a sliding run of records). #[repr(C)] pub struct moq_json_window_config { @@ -520,13 +550,9 @@ pub struct moq_json_value { /// The length in bytes of `json`. pub json_len: usize, - /// The timestamp of the frame that carried the value in microseconds, or 0 when - /// `timestamp_present` is false. Rounded down to a whole microsecond, so a tick on a track - /// like 90 kHz may not survive a read and republish exactly. - pub timestamp_us: u64, - - /// Whether the frame carries a timestamp. A value read from an untimed track does not. - pub timestamp_present: bool, + /// The timestamp of the frame that carried the value, or NULL on an untimed track. + /// Valid as long as `json`. + pub timestamp: *const moq_timestamp, } /// Which change a [moq_json_window_event] reports. @@ -562,13 +588,10 @@ pub struct moq_json_window_event { /// The length in bytes of `json`. pub json_len: usize, - /// The timestamp of the frame that carried the change in microseconds, or 0 when - /// `timestamp_present` is false. A record first learned of from a group's restatement (after - /// a join, or while behind) carries that frame's time, not its original push time. - pub timestamp_us: u64, - - /// Whether the frame carries a timestamp. A change read from an untimed track does not. - pub timestamp_present: bool, + /// The timestamp of the frame that carried the change, or NULL on an untimed track. Valid + /// until the event is freed. A record first learned of from a group's restatement (after a + /// join, or while behind) carries that frame's time, not its original push time. + pub timestamp: *const moq_timestamp, } /// Information about a frame of media. @@ -579,13 +602,9 @@ pub struct moq_frame { /// The length in bytes of `payload`. pub payload_size: usize, - /// The presentation timestamp of the frame in microseconds, or 0 when - /// `timestamp_present` is false. - pub timestamp_us: u64, - - /// Whether the frame carries a timestamp. Media frames always do; a raw frame read - /// from an untimed track does not. - pub timestamp_present: bool, + /// The presentation timestamp of the frame, or NULL on an untimed track. Media frames + /// always have one. Valid as long as `payload`. + pub timestamp: *const moq_timestamp, /// Whether this frame opens a group or is a video keyframe; audio is true only at a group start. pub keyframe: bool, @@ -600,9 +619,9 @@ pub struct moq_media_read { pub frame: moq_frame, /// Lost media for a gap read; what follows does not continue it. pub gap: crate::moq_decode_gap, - /// Where a stopped encoder's media stops, in microseconds. Following frames before - /// this point are its remaining media; the first at or past it comes from a fresh encoder. - pub end_us: u64, + /// Where a stopped encoder's media stops. Following frames before this point are its + /// remaining media; the first at or past it comes from a fresh encoder. + pub end: moq_timestamp, } /// A best-effort raw track datagram delivered via [moq_consume_datagrams]. @@ -613,12 +632,9 @@ pub struct moq_datagram { /// The length in bytes of `payload`. pub payload_size: usize, - /// The presentation timestamp of the datagram in microseconds, or 0 when - /// `timestamp_present` is false. - pub timestamp_us: u64, - - /// Whether the datagram carries a timestamp. One read from an untimed track does not. - pub timestamp_present: bool, + /// The presentation timestamp of the datagram, or NULL on an untimed track. Valid as + /// long as `payload`. + pub timestamp: *const moq_timestamp, /// Per-track sequence number, drawn from the same namespace as groups. pub sequence: u64, @@ -642,8 +658,7 @@ pub struct moq_track_info { /// Per-frame timescale in ticks per second. pub timescale: u64, - /// Whether `timescale` is set. When false, the default microsecond timescale - /// applies, matching the `timestamp_us` units used everywhere else in this ABI. + /// Whether `timescale` is set. When false, a microsecond timescale applies. pub timescale_present: bool, /// A joining subscriber asks for a new group once the newest group's bytes after its @@ -661,8 +676,7 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { type Error = Error; fn try_from(info: &moq_track_info) -> Result { - // Raw tracks default to a microsecond timescale, matching the C ABI's - // timestamp_us units. An explicit timescale below overrides it. + // Raw tracks default to a microsecond timescale; an explicit one below overrides it. let mut out = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) .with_priority(info.priority); @@ -788,8 +802,8 @@ pub struct moq_anchor { /// The group, or with `MOQ_ANCHOR_RELATIVE` how many groups before the latest one /// (0 is the latest, and an offset past the first group clamps to it). pub group: u64, - /// The presentation time in microseconds, read only with `MOQ_ANCHOR_TIME`. - pub timestamp_us: u64, + /// The presentation time, read only with `MOQ_ANCHOR_TIME`. + pub timestamp: moq_timestamp, } /// How a [moq_anchor] names its position. @@ -820,9 +834,7 @@ fn parse_anchor(anchor: &moq_anchor) -> Result { Ok(match anchor.kind { v if v == moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32 => moq_net::track::Anchor::Absolute(anchor.group), v if v == moq_anchor_kind::MOQ_ANCHOR_RELATIVE as u32 => moq_net::track::Anchor::Relative(anchor.group), - v if v == moq_anchor_kind::MOQ_ANCHOR_TIME as u32 => { - moq_net::track::Anchor::Time(moq_net::Timestamp::from_micros(anchor.timestamp_us)?) - } + v if v == moq_anchor_kind::MOQ_ANCHOR_TIME as u32 => moq_net::track::Anchor::Time(anchor.timestamp.try_into()?), _ => return Err(Error::InvalidCode), }) } @@ -2800,7 +2812,6 @@ pub extern "C" fn moq_publish_container_finish(container: u32) -> i32 { /// Write data to a track. /// /// The encoding of `data` depends on the track `format`. -/// The timestamp is in microseconds. /// /// Returns a zero on success, or a negative code on failure. /// @@ -2811,13 +2822,12 @@ pub unsafe extern "C" fn moq_publish_media_frame( media: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: moq_timestamp, ) -> i32 { ffi::enter(move || { let media = ffi::parse_id(media)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let timestamp = hang::container::Timestamp::from_micros(timestamp_us)?; - State::lock().publish.media_frame(media, payload, timestamp) + State::lock().publish.media_frame(media, payload, timestamp.try_into()?) }) } @@ -3121,31 +3131,33 @@ pub extern "C" fn moq_publish_track_group_at(track: u32, sequence: u64) -> i32 { /// Write a single-frame group to a raw track with a timestamp. /// /// Convenience for the common one-frame-per-group pattern. Equivalent to -/// appending a group, writing one frame, and finishing it. -/// The timestamp is in microseconds. +/// appending a group, writing one frame, and finishing it. The timestamp is +/// converted to the track's timescale; NULL writes an untimed frame, which only +/// an untimed track accepts. /// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure that payload is a valid pointer to payload_size bytes of data. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_track_frame( track: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: *const moq_timestamp, ) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let timestamp = moq_net::Timestamp::from_micros(timestamp_us)?; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; State::lock().publish.track_frame(track, timestamp, payload) }) } /// Send a best-effort datagram on a raw track created by [moq_publish_track]. /// -/// Takes `payload` then `timestamp_us`, matching [moq_publish_track_frame]. The payload must +/// Takes `payload` then `timestamp`, matching [moq_publish_track_frame]. The payload must /// be at most 1200 bytes. On success the datagram's per-track sequence number (shared with the /// group namespace) is written to `out_sequence` when it is non-NULL. Datagrams are /// delivered only on transports and wire versions with a datagram channel; there is no @@ -3155,19 +3167,21 @@ pub unsafe extern "C" fn moq_publish_track_frame( /// /// # Safety /// - The caller must ensure that payload is a valid pointer to payload_size bytes of data. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. /// - `out_sequence` must be NULL or a valid pointer to a `uint64_t`. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_track_datagram( track: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: *const moq_timestamp, out_sequence: *mut u64, ) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let sequence = State::lock().publish.track_datagram(track, timestamp_us, payload)?; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + let sequence = State::lock().publish.track_datagram(track, timestamp, payload)?; if let Some(out) = unsafe { out_sequence.as_mut() } { *out = sequence; } @@ -3512,23 +3526,25 @@ pub extern "C" fn moq_group_request_free(request: u32) -> i32 { /// Write a frame into a raw group created by [moq_publish_track_group]. /// -/// The timestamp is in microseconds. +/// The timestamp is converted to the track's timescale; NULL writes an untimed +/// frame, which only an untimed track accepts. /// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure that payload is a valid pointer to payload_size bytes of data. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_group_frame( group: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: *const moq_timestamp, ) -> i32 { ffi::enter(move || { let group = ffi::parse_id(group)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let timestamp = moq_net::Timestamp::from_micros(timestamp_us)?; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; State::lock().publish.group_frame(group, timestamp, payload) }) } @@ -3585,17 +3601,27 @@ pub unsafe extern "C" fn moq_publish_json_snapshot( /// Publish a new value to a JSON snapshot track. `value` is a UTF-8 JSON document. A no-op if /// unchanged from the previous update. /// +/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; +/// NULL stamps the broadcast clock's current time. +/// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure `value` is a valid pointer to `value_len` bytes. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_json_snapshot_update(json: u32, value: *const c_char, value_len: usize) -> i32 { +pub unsafe extern "C" fn moq_publish_json_snapshot_update( + json: u32, + value: *const c_char, + value_len: usize, + timestamp: *const moq_timestamp, +) -> i32 { ffi::enter(move || { let json = ffi::parse_id(json)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - State::lock().publish.json_snapshot_update(json, value) + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + State::lock().publish.json_snapshot_update(json, value, timestamp) }) } @@ -3634,17 +3660,27 @@ pub unsafe extern "C" fn moq_publish_json_stream(broadcast: u32, name: *const c_ /// Append one record to a JSON stream track. `value` is a UTF-8 JSON document. /// +/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; +/// NULL stamps the broadcast clock's current time. +/// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure `value` is a valid pointer to `value_len` bytes. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_json_stream_append(stream: u32, value: *const c_char, value_len: usize) -> i32 { +pub unsafe extern "C" fn moq_publish_json_stream_append( + stream: u32, + value: *const c_char, + value_len: usize, + timestamp: *const moq_timestamp, +) -> i32 { ffi::enter(move || { let stream = ffi::parse_id(stream)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - State::lock().publish.json_stream_append(stream, value) + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + State::lock().publish.json_stream_append(stream, value, timestamp) }) } @@ -4052,7 +4088,7 @@ pub extern "C" fn moq_consume_audio_cancel(track: u32) -> i32 { } /// Read an encoded media frame, gap, or encoder end delivered by a media callback. -/// Payload pointers borrow the read until [`moq_consume_read_free`]. +/// Payload and timestamp pointers borrow the read until [`moq_consume_read_free`]. /// /// # Safety /// - `dst` must point to a writable [`moq_media_read`]. @@ -4150,10 +4186,9 @@ pub unsafe extern "C" fn moq_consume_track_update(track: u32, subscription: *con /// Read a raw frame's payload delivered via the [moq_consume_track] callback. /// /// Fills `dst.payload` / `dst.payload_size`; the pointer is valid until the -/// frame is released with [moq_consume_track_frame_free]. `dst.timestamp_us` is the -/// frame presentation timestamp in microseconds, when `dst.timestamp_present` says it -/// has one. `dst.keyframe` is reported as -/// false because raw tracks do not parse codec metadata. +/// frame is released with [moq_consume_track_frame_free], and so is `dst.timestamp`, +/// NULL on an untimed track. `dst.keyframe` is reported as false because raw tracks +/// do not parse codec metadata. /// /// Returns a zero on success, or a negative code on failure. /// @@ -4229,8 +4264,8 @@ pub unsafe extern "C" fn moq_consume_datagrams( /// Read a datagram delivered via the [moq_consume_datagrams] callback. /// /// Fills `dst.payload` / `dst.payload_size` (valid until the datagram is released with -/// [moq_consume_datagram_free]), plus `dst.timestamp_us` (when `dst.timestamp_present`) -/// and `dst.sequence`. +/// [moq_consume_datagram_free]), plus `dst.timestamp` (NULL on an untimed track, and valid +/// as long as the payload) and `dst.sequence`. /// /// Returns a zero on success, or a negative code on failure. /// @@ -4386,8 +4421,8 @@ pub extern "C" fn moq_consume_json_window_event_free(event: u32) -> i32 { /// Read a JSON value delivered via a [moq_consume_json_snapshot] or [moq_consume_json_stream] callback. /// -/// Fills `dst.json` / `dst.json_len` and the frame timestamp; the pointer is valid until the value is released with -/// [moq_consume_json_value_free]. +/// Fills `dst.json` / `dst.json_len` and the frame timestamp; both pointers are valid until the value is released +/// with [moq_consume_json_value_free]. /// /// Returns a zero on success, or a negative code on failure. /// diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index 39ff8596705..db120d8b4ae 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -20,7 +20,7 @@ use tokio::sync::oneshot; use crate::decode::Read; use crate::ffi::OnStatus; -use crate::{moq_decode_gap, moq_decode_read_kind, moq_decode_start}; +use crate::{moq_decode_gap, moq_decode_read_kind, moq_decode_start, moq_timestamp}; use crate::task::Task; use crate::{Error, Id, NonZeroSlab, Shared, State, ffi}; @@ -137,8 +137,8 @@ pub struct moq_audio_decoder_output { /// (the publisher copies before returning). #[repr(C)] pub struct moq_audio_frame { - /// The presentation timestamp in microseconds. - pub timestamp_us: u64, + /// The presentation timestamp. + pub timestamp: moq_timestamp, /// The raw frame bytes in the configured layout. pub data: *const u8, /// The length in bytes of `data`. @@ -156,11 +156,11 @@ pub struct moq_audio_read { /// The lost span, for [moq_decode_read_kind::MOQ_DECODE_READ_GAP]. What follows does /// not continue what came before. pub gap: moq_decode_gap, - /// Where the stopped encoder's media stops in microseconds, for + /// Where the stopped encoder's media stops, for /// [moq_decode_read_kind::MOQ_DECODE_READ_END]. Frames that follow and start before it /// are the stopped encoder's remaining media; the first at or past it comes from a fresh /// encoder. - pub end_us: u64, + pub end: moq_timestamp, } // ---- State extensions (used internally by lib.rs) ---- @@ -291,7 +291,7 @@ impl Audio { read = consumer.read() => match read { Ok(Some(moq_audio::decode::Read::Frame(frame))) => Read::Frame(frame), Ok(Some(moq_audio::decode::Read::Gap { timestamp, duration })) => Read::gap(timestamp, duration)?, - Ok(Some(moq_audio::decode::Read::End { end })) => Read::end(end)?, + Ok(Some(moq_audio::decode::Read::End { end })) => Read::end(end), Ok(None) => return Ok(()), // One packet the codec rejected is that packet's problem: the // decoder stays usable, so drop it and keep the subscription rather @@ -318,29 +318,20 @@ impl Audio { /// Borrow a delivered read, and a frame's samples, until its handle is freed. pub fn read_info(&self, id: Id, dst: &mut moq_audio_read) -> Result<(), Error> { let read = self.reads.get(id).ok_or(Error::FrameNotFound)?; - let (kind, gap, end_us) = read.info(); + let (kind, gap, end) = read.info(); let frame = match read { Read::Frame(frame) => moq_audio_frame { - // The C ABI carries plain microseconds, so flatten the scaled - // `Timestamp` here at the boundary. Saturating rather than erroring: - // this is a getter on a frame we already decoded, and a u64 overflow - // needs a timestamp ~580,000 years out. - timestamp_us: u64::try_from(frame.timestamp.as_micros()).unwrap_or(u64::MAX), + timestamp: frame.timestamp.into(), data: frame.data.as_ptr(), data_size: frame.data.len(), }, _ => moq_audio_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), data: std::ptr::null(), data_size: 0, }, }; - *dst = moq_audio_read { - kind, - frame, - gap, - end_us, - }; + *dst = moq_audio_read { kind, frame, gap, end }; Ok(()) } @@ -479,9 +470,7 @@ pub unsafe extern "C" fn moq_encode_audio_frame(producer: u32, frame: *const moq let frame = unsafe { frame.as_ref() }.ok_or(Error::InvalidPointer)?; let data = unsafe { ffi::parse_slice(frame.data, frame.data_size)? }; - // The C ABI carries plain microseconds; scale them at the boundary. - let timestamp = moq_net::Timestamp::from_micros(frame.timestamp_us).map_err(moq_audio::Error::from)?; - let owned = moq_audio::Frame::new(Bytes::copy_from_slice(data), timestamp); + let owned = moq_audio::Frame::new(Bytes::copy_from_slice(data), frame.timestamp.try_into()?); let producer = State::lock().audio.producer(producer)?; producer diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index b187e78da9f..86ad1f72299 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -12,7 +12,7 @@ use crate::ffi::OnStatus; use crate::task::Task; use crate::{ Error, Id, NonZeroSlab, State, moq_audio_config, moq_datagram, moq_frame, moq_json_value, moq_json_window_event, - moq_json_window_kind, moq_section, moq_string, moq_video_config, moq_video_properties, + moq_json_window_kind, moq_section, moq_string, moq_timestamp, moq_video_config, moq_video_properties, }; struct ConsumeCatalog { @@ -146,43 +146,47 @@ enum RawStep { Stop, } -/// A raw frame, datagram, or JSON value timestamp in microseconds, `None` when untimed. -fn timestamp_us(timestamp: Option) -> Result, Error> { - timestamp - .map(|timestamp| timestamp.as_micros().try_into()) - .transpose() - .map_err(|_| Error::TimestampOverflow(moq_net::TimeOverflow)) +/// A buffered read plus the timestamp C borrows through a pointer, `None` when untimed. +/// +/// Boxed because the slab moves its entries as it grows, and the pointer must stay valid +/// until the read is freed. +struct Timed { + item: T, + timestamp: Option>, } -/// A JSON value pre-serialized to a string, with its frame timestamp. -struct JsonValue { - json: String, - timestamp_us: Option, -} +impl Timed { + fn new(item: T, timestamp: Option) -> Self { + Self { + item, + timestamp: timestamp.map(|timestamp| Box::new(timestamp.into())), + } + } -impl JsonValue { - fn new(value: moq_net::Timed) -> Result { - Ok(Self { - json: serde_json::to_string(&value.value)?, - timestamp_us: timestamp_us(value.at)?, - }) + /// The timestamp pointer handed to C, NULL when untimed. + fn timestamp(&self) -> *const moq_timestamp { + self.timestamp.as_deref().map_or(std::ptr::null(), std::ptr::from_ref) } } -/// A JSON window event, its record pre-serialized to a string, with its frame timestamp. +/// A JSON value pre-serialized to a string, with its frame timestamp. +fn json_value(value: moq_net::Timed) -> Result, Error> { + Ok(Timed::new(serde_json::to_string(&value.value)?, value.at)) +} + +/// A JSON window event, its record pre-serialized to a string. struct JsonWindowEvent { kind: moq_json_window_kind, range: std::ops::Range, /// The pushed record, `None` for a pop or skip. json: Option, - timestamp_us: Option, } impl JsonWindowEvent { - fn new(event: moq_net::Timed>) -> Result { + /// Pre-serialize an event, keeping its frame timestamp. + fn new(event: moq_net::Timed>) -> Result, Error> { use moq_json::window::Event; - let timestamp_us = timestamp_us(event.at)?; let (kind, range, json) = match event.value { Event::Push { index, value } => ( moq_json_window_kind::MOQ_JSON_WINDOW_KIND_PUSH, @@ -193,12 +197,7 @@ impl JsonWindowEvent { Event::Skip(range) => (moq_json_window_kind::MOQ_JSON_WINDOW_KIND_SKIP, range, None), event => return Err(Error::Json(format!("unsupported window event: {event:?}"))), }; - Ok(Self { - kind, - range, - json, - timestamp_us, - }) + Ok(Timed::new(Self { kind, range, json }, event.at)) } } @@ -217,28 +216,28 @@ pub struct Consume { track_task: NonZeroSlab, /// Buffered frames ready for consumption. - reads: NonZeroSlab>, + reads: NonZeroSlab>>, /// Raw track consumer tasks (no media/container framing). raw_task: NonZeroSlab, /// Buffered raw frames ready for consumption. - raw_frame: NonZeroSlab, + raw_frame: NonZeroSlab>, /// Raw track datagram consumer tasks (best-effort, parallel to `raw_task`). datagram_task: NonZeroSlab, /// Buffered datagrams ready for consumption. - datagram: NonZeroSlab, + datagram: NonZeroSlab>, /// JSON consumer tasks (snapshot, stream, and window share this slab). json_task: NonZeroSlab, /// Buffered JSON values ready for consumption. - json_value: NonZeroSlab, + json_value: NonZeroSlab>, /// Buffered JSON window events ready for consumption. - json_window_event: NonZeroSlab, + json_window_event: NonZeroSlab>, } impl Consume { @@ -550,9 +549,12 @@ impl Consume { biased; _ = &mut close => return Ok(()), read = track.read() => match read? { - Some(moq_mux::container::Read::Frame { frame, .. }) => Read::Frame(frame), + Some(moq_mux::container::Read::Frame { frame, .. }) => { + let timestamp = frame.timestamp; + Read::Frame(Timed::new(frame, Some(timestamp))) + } Some(moq_mux::container::Read::Gap { timestamp, duration }) => Read::gap(timestamp, duration)?, - Some(moq_mux::container::Read::End { end, .. }) => Read::end(end)?, + Some(moq_mux::container::Read::End { end, .. }) => Read::end(end), None => return Ok(()), }, }; @@ -570,29 +572,22 @@ impl Consume { /// Read the tagged media item; payload pointers borrow it until [`Self::read_free`]. pub fn read(&self, id: Id, dst: &mut crate::moq_media_read) -> Result<(), Error> { let read = self.reads.get(id).ok_or(Error::FrameNotFound)?; - let (kind, gap, end_us) = read.info(); + let (kind, gap, end) = read.info(); let frame = match read { Read::Frame(f) => moq_frame { - payload: f.payload.as_ptr(), - payload_size: f.payload.len(), - timestamp_us: f.timestamp.as_micros().try_into().map_err(|_| moq_net::TimeOverflow)?, - timestamp_present: true, - keyframe: f.keyframe, + payload: f.item.payload.as_ptr(), + payload_size: f.item.payload.len(), + timestamp: f.timestamp(), + keyframe: f.item.keyframe, }, _ => moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }, }; - *dst = crate::moq_media_read { - kind, - frame, - gap, - end_us, - }; + *dst = crate::moq_media_read { kind, frame, gap, end }; Ok(()) } @@ -730,6 +725,7 @@ impl Consume { }; // Hold the lock only to buffer the read; release it before the callback. + let frame = Timed::new(frame.payload, frame.timestamp); let frame_id = State::lock().consume.raw_frame.insert(frame)?; callback.call(Ok(frame_id)); } @@ -762,13 +758,11 @@ impl Consume { /// frame is released with [`Self::raw_frame_close`]. pub fn raw_frame(&self, frame: Id, dst: &mut moq_frame) -> Result<(), Error> { let frame = self.raw_frame.get(frame).ok_or(Error::FrameNotFound)?; - let timestamp_us = timestamp_us(frame.timestamp)?; *dst = moq_frame { - payload: frame.payload.as_ptr(), - payload_size: frame.payload.len(), - timestamp_us: timestamp_us.unwrap_or_default(), - timestamp_present: timestamp_us.is_some(), + payload: frame.item.as_ptr(), + payload_size: frame.item.len(), + timestamp: frame.timestamp(), keyframe: false, }; @@ -827,7 +821,8 @@ impl Consume { }; // Hold the lock only to buffer the datagram; release it before the callback. - let id = State::lock().consume.datagram.insert(datagram)?; + let timestamp = datagram.timestamp; + let id = State::lock().consume.datagram.insert(Timed::new(datagram, timestamp))?; callback.call(Ok(id)); } } @@ -841,14 +836,11 @@ impl Consume { pub fn datagram(&self, datagram: Id, dst: &mut moq_datagram) -> Result<(), Error> { let value = self.datagram.get(datagram).ok_or(Error::FrameNotFound)?; - let timestamp_us = timestamp_us(value.timestamp)?; - *dst = moq_datagram { - payload: value.payload.as_ptr(), - payload_size: value.payload.len(), - timestamp_us: timestamp_us.unwrap_or_default(), - timestamp_present: timestamp_us.is_some(), - sequence: value.sequence, + payload: value.item.payload.as_ptr(), + payload_size: value.item.payload.len(), + timestamp: value.timestamp(), + sequence: value.item.sequence, }; Ok(()) @@ -927,7 +919,7 @@ impl Consume { // Serialize before locking, hold the lock only to buffer the value, and release it // before the callback. - let value = JsonValue::new(value)?; + let value = json_value(value)?; let value_id = State::lock().consume.json_value.insert(value)?; callback.call(Ok(value_id)); } @@ -981,7 +973,7 @@ impl Consume { }, }; - let value = JsonValue::new(value)?; + let value = json_value(value)?; let value_id = State::lock().consume.json_value.insert(value)?; callback.call(Ok(value_id)); } @@ -1053,10 +1045,9 @@ impl Consume { let value = self.json_value.get(value).ok_or(Error::FrameNotFound)?; *dst = moq_json_value { - json: value.json.as_ptr() as *const c_char, - json_len: value.json.len(), - timestamp_us: value.timestamp_us.unwrap_or_default(), - timestamp_present: value.timestamp_us.is_some(), + json: value.item.as_ptr() as *const c_char, + json_len: value.item.len(), + timestamp: value.timestamp(), }; Ok(()) @@ -1072,19 +1063,18 @@ impl Consume { /// until the event is released with [`Self::json_window_event_close`]. pub fn json_window_event(&self, event: Id, dst: &mut moq_json_window_event) -> Result<(), Error> { let event = self.json_window_event.get(event).ok_or(Error::FrameNotFound)?; - let (json, json_len) = match &event.json { + let (json, json_len) = match &event.item.json { Some(json) => (json.as_ptr() as *const c_char, json.len()), None => (std::ptr::null(), 0), }; *dst = moq_json_window_event { - kind: event.kind, - start: event.range.start, - end: event.range.end, + kind: event.item.kind, + start: event.item.range.start, + end: event.item.range.end, json, json_len, - timestamp_us: event.timestamp_us.unwrap_or_default(), - timestamp_present: event.timestamp_us.is_some(), + timestamp: event.timestamp(), }; Ok(()) @@ -1203,6 +1193,10 @@ mod read_tests { track.finish().unwrap(); run.await.unwrap(); assert_eq!(ids.len(), 3); + let micros = |value| moq_timestamp { + value, + scale: 1_000_000, + }; let mut read = std::mem::MaybeUninit::::uninit(); for (index, id) in ids.into_iter().enumerate() { assert!(id > 0); @@ -1215,20 +1209,20 @@ mod read_tests { unsafe { std::slice::from_raw_parts(read.frame.payload, read.frame.payload_size) }, b"encoded" ); - assert_eq!(read.frame.timestamp_us, 10_000); - assert!(read.frame.timestamp_present && read.frame.keyframe); + assert_eq!(unsafe { *read.frame.timestamp }, micros(10_000)); + assert!(read.frame.keyframe); assert_eq!(read.gap.duration_us, 0); - assert_eq!(read.end_us, 0); + assert_eq!(read.end, moq_timestamp::default()); } 1 => { assert_eq!(read.kind, crate::moq_decode_read_kind::MOQ_DECODE_READ_GAP); - assert_eq!((read.gap.timestamp_us, read.gap.duration_us), (10_000, 10_000)); - assert!(read.frame.payload.is_null()); - assert_eq!(read.end_us, 0); + assert_eq!((read.gap.timestamp, read.gap.duration_us), (micros(10_000), 10_000)); + assert!(read.frame.payload.is_null() && read.frame.timestamp.is_null()); + assert_eq!(read.end, moq_timestamp::default()); } 2 => { assert_eq!(read.kind, crate::moq_decode_read_kind::MOQ_DECODE_READ_END); - assert_eq!(read.end_us, 20_000); + assert_eq!(read.end, micros(20_000)); assert!(read.frame.payload.is_null()); assert_eq!(read.gap.duration_us, 0); } diff --git a/rs/moq-c/src/decode.rs b/rs/moq-c/src/decode.rs index 2c19d46ea1f..a7bedc6f41f 100644 --- a/rs/moq-c/src/decode.rs +++ b/rs/moq-c/src/decode.rs @@ -3,7 +3,7 @@ //! Encoded media and both decoders hand over the same three kinds of read, so a C player //! handles loss and encoder ends alike for every media type. -use crate::Error; +use crate::{Error, moq_timestamp}; /// Which kind of media read was delivered: a frame, or a break between frames. #[repr(C)] @@ -52,53 +52,53 @@ impl moq_decode_start { #[repr(C)] #[derive(Clone, Copy, Debug, Default)] pub struct moq_decode_gap { - /// The furthest presentation point already read, in microseconds. - pub timestamp_us: u64, + /// The furthest presentation point already read. + pub timestamp: moq_timestamp, /// An upper bound on how long until the next frame resumes, in microseconds. pub duration_us: u64, } -/// A delivered read held by its id, with its timestamps already in the C ABI's microseconds. +/// A delivered read held by its id. #[derive(Clone)] pub(crate) enum Read { Frame(F), Gap(moq_decode_gap), - End { end_us: u64 }, + End(moq_timestamp), } impl Read { pub(crate) fn gap(timestamp: moq_net::Timestamp, duration: moq_net::Timestamp) -> Result { Ok(Self::Gap(moq_decode_gap { - timestamp_us: micros(timestamp)?, - duration_us: micros(duration)?, + timestamp: timestamp.into(), + duration_us: duration + .as_micros() + .try_into() + .map_err(|_| Error::TimestampOverflow(moq_net::TimeOverflow))?, })) } - pub(crate) fn end(end: moq_net::Timestamp) -> Result { - Ok(Self::End { end_us: micros(end)? }) + pub(crate) fn end(end: moq_net::Timestamp) -> Self { + Self::End(end.into()) } /// The C kind, plus the gap and end fields a non-frame read fills. - pub(crate) fn info(&self) -> (moq_decode_read_kind, moq_decode_gap, u64) { + pub(crate) fn info(&self) -> (moq_decode_read_kind, moq_decode_gap, moq_timestamp) { match self { Self::Frame(_) => ( moq_decode_read_kind::MOQ_DECODE_READ_FRAME, moq_decode_gap::default(), - 0, + moq_timestamp::default(), ), - Self::Gap(gap) => (moq_decode_read_kind::MOQ_DECODE_READ_GAP, *gap, 0), - Self::End { end_us } => ( + Self::Gap(gap) => ( + moq_decode_read_kind::MOQ_DECODE_READ_GAP, + *gap, + moq_timestamp::default(), + ), + Self::End(end) => ( moq_decode_read_kind::MOQ_DECODE_READ_END, moq_decode_gap::default(), - *end_us, + *end, ), } } } - -fn micros(timestamp: moq_net::Timestamp) -> Result { - timestamp - .as_micros() - .try_into() - .map_err(|_| Error::TimestampOverflow(moq_net::TimeOverflow)) -} diff --git a/rs/moq-c/src/ffi.rs b/rs/moq-c/src/ffi.rs index e4a03aef315..be21fc414ee 100644 --- a/rs/moq-c/src/ffi.rs +++ b/rs/moq-c/src/ffi.rs @@ -508,6 +508,16 @@ pub unsafe fn parse_slice<'a>(data: *const u8, size: usize) -> Result<&'a [u8], Ok(data) } +/// Parse an optional timestamp, NULL meaning untimed. +/// +/// # Safety +/// `timestamp` must be NULL or a valid pointer to a [crate::moq_timestamp]. +pub unsafe fn parse_timestamp(timestamp: *const crate::moq_timestamp) -> Result, Error> { + Ok(unsafe { timestamp.as_ref() } + .map(|×tamp| timestamp.try_into()) + .transpose()?) +} + #[cfg(test)] mod tests { diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 0f2bf7defb7..810ca261283 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -252,8 +252,8 @@ impl std::ops::DerefMut for Kept { } } -// Legacy C data methods stamp writes on one fixed broadcast clock without retaining -// another catalog handle after a failed stream retires its listing. +// C data methods stamp a write the caller left unstamped on one fixed broadcast clock, +// without retaining another catalog handle after a failed stream retires its listing. struct Data { producer: T, clock: moq_mux::Clock, @@ -1134,8 +1134,13 @@ impl Publish { self.groups.insert(group) } - /// Write a single-frame group to a raw track with an explicit timestamp. - pub fn track_frame(&mut self, track: Id, timestamp: moq_net::Timestamp, payload: &[u8]) -> Result<(), Error> { + /// Write a single-frame group to a raw track, `None` when untimed. + pub fn track_frame( + &mut self, + track: Id, + timestamp: Option, + payload: &[u8], + ) -> Result<(), Error> { let track = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; track.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) @@ -1146,9 +1151,13 @@ impl Publish { /// The payload must be at most [`moq_net::MAX_DATAGRAM_PAYLOAD`] bytes. Datagrams are /// delivered only on transports and wire versions with a datagram channel; there is no /// group fallback. - pub fn track_datagram(&mut self, track: Id, timestamp_us: u64, payload: &[u8]) -> Result { + pub fn track_datagram( + &mut self, + track: Id, + timestamp: Option, + payload: &[u8], + ) -> Result { let track = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; - let timestamp = moq_net::Timestamp::from_micros(timestamp_us)?; Ok(track.append_datagram(timestamp, bytes::Bytes::copy_from_slice(payload))?) } @@ -1280,10 +1289,15 @@ impl Publish { } /// Publish a new value to a JSON snapshot track. A no-op if unchanged. - pub fn json_snapshot_update(&mut self, json: Id, value: serde_json::Value) -> Result<(), Error> { + pub fn json_snapshot_update( + &mut self, + json: Id, + value: serde_json::Value, + timestamp: Option, + ) -> Result<(), Error> { let json = &mut self.json_snapshot.get_mut(json).ok_or(Error::TrackNotFound)?.data; - json.producer - .update(moq_net::Timed::from(&value).at(json.clock.now()))?; + let at = timestamp.unwrap_or_else(|| json.clock.now()); + json.producer.update(moq_net::Timed::from(&value).at(at))?; Ok(()) } @@ -1309,11 +1323,15 @@ impl Publish { } /// Append one record to a JSON stream track. - pub fn json_stream_append(&mut self, stream: Id, value: serde_json::Value) -> Result<(), Error> { + pub fn json_stream_append( + &mut self, + stream: Id, + value: serde_json::Value, + timestamp: Option, + ) -> Result<(), Error> { let producer = self.json_stream.get_mut(stream).ok_or(Error::TrackNotFound)?; - producer - .producer - .append(moq_net::Timed::from(&value).at(producer.clock.now()))?; + let at = timestamp.unwrap_or_else(|| producer.clock.now()); + producer.producer.append(moq_net::Timed::from(&value).at(at))?; Ok(()) } @@ -1390,8 +1408,13 @@ impl Publish { Ok(()) } - /// Write a frame into a raw group with an explicit timestamp. - pub fn group_frame(&mut self, group: Id, timestamp: moq_net::Timestamp, payload: &[u8]) -> Result<(), Error> { + /// Write a frame into a raw group, `None` when untimed. + pub fn group_frame( + &mut self, + group: Id, + timestamp: Option, + payload: &[u8], + ) -> Result<(), Error> { let group = self.groups.get_mut(group).ok_or(Error::GroupNotFound)?; group.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) @@ -1551,11 +1574,11 @@ mod children_tests { } let json = serde_json::Value::Null; assert!(matches!( - state.publish.json_snapshot_update(json_snapshot, json.clone()), + state.publish.json_snapshot_update(json_snapshot, json.clone(), None), Err(Error::TrackNotFound) )); assert!(matches!( - state.publish.json_stream_append(json_stream, json), + state.publish.json_stream_append(json_stream, json, None), Err(Error::TrackNotFound) )); } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 2a89a0732df..90edcc5228a 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -7,6 +7,19 @@ use std::time::Duration; const TIMEOUT: Duration = Duration::from_secs(10); +/// A timestamp of `value` microseconds. +fn micros(value: u64) -> moq_timestamp { + moq_timestamp { + value, + scale: 1_000_000, + } +} + +/// The timestamp a read points at, `None` when untimed. +fn read_timestamp(timestamp: *const moq_timestamp) -> Option { + unsafe { timestamp.as_ref() }.copied() +} + /// A ten-second max delay, the media consumers' usual budget here. const TEN_SECONDS: moq_delay = moq_delay { min_us: 0, @@ -319,14 +332,14 @@ fn video_read(id: u32) -> (i32, moq_video_read) { let mut read = moq_video_read { kind: moq_decode_read_kind::MOQ_DECODE_READ_END, frame: moq_video_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), width: 0, height: 0, data: std::ptr::null(), data_size: 0, }, gap: moq_decode_gap::default(), - end_us: 0, + end: moq_timestamp::default(), }; let code = unsafe { moq_decode_video_read(id, &mut read) }; (code, read) @@ -1307,7 +1320,7 @@ fn raw_loc_video_uses_the_declared_catalog_container() { let loc = moq_loc::encode(timestamp_us, payload).unwrap(); let group = id(moq_publish_track_group(track)); assert_eq!( - unsafe { moq_publish_group_frame(group, loc.as_ptr(), loc.len(), timestamp_us) }, + unsafe { moq_publish_group_frame(group, loc.as_ptr(), loc.len(), µs(timestamp_us)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -1316,13 +1329,15 @@ fn raw_loc_video_uses_the_declared_catalog_container() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); - assert_eq!(frame.timestamp_us, timestamp_us); - assert!(frame.timestamp_present, "a media frame is always timed"); + assert_eq!( + read_timestamp(frame.timestamp), + Some(micros(timestamp_us)), + "a media frame is always timed" + ); assert!(frame.keyframe); assert_eq!( unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, @@ -1637,8 +1652,8 @@ fn publish_track_invalid_broadcast() { }; assert!(unsafe { moq_publish_track(0, name.as_ptr() as *const c_char, name.len(), &info) } < 0); assert!(moq_publish_track_group(9999) < 0); - assert!(unsafe { moq_publish_track_frame(9999, name.as_ptr(), name.len(), 0) } < 0); - assert!(unsafe { moq_publish_group_frame(9999, name.as_ptr(), name.len(), 0) } < 0); + assert!(unsafe { moq_publish_track_frame(9999, name.as_ptr(), name.len(), µs(0)) } < 0); + assert!(unsafe { moq_publish_group_frame(9999, name.as_ptr(), name.len(), µs(0)) } < 0); assert!(moq_publish_track_finish(9999) < 0); assert!(moq_publish_group_finish(9999) < 0); @@ -1673,63 +1688,177 @@ fn publish_track_with_info_rejects_invalid_timescale() { assert_eq!(moq_publish_close(broadcast), 0); } -/// A raw frame read from an untimed track reports no timestamp. The C API only publishes -/// timed tracks, so the track and its frame come from moq-net. +/// Raw frames, datagrams, and JSON values read back exactly the timestamp written: a 90 kHz +/// tick that microseconds cannot express, a present zero, and untimed. The C API only creates +/// timed tracks, so the tracks and the JSON producer come from moq-net. #[test] -fn an_untimed_raw_frame_reads_untimed() { +fn timestamps_round_trip_exactly() { let origin = id(moq_origin_create()); - let path = b"raw-untimed"; + let path = b"exact-timestamps"; let broadcast = publish_broadcast(origin, path); + let consume = request_broadcast(origin, path); - let track_name = b"data"; - let track = State::lock() - .publish - .track( - Id::try_from(broadcast).unwrap(), - "data", - Some(moq_net::track::Info::default().with_timescale(None)), - ) - .unwrap(); + let tick = moq_timestamp { + value: 1, + scale: 90_000, + }; + let zero = moq_timestamp { + value: 0, + scale: 90_000, + }; + for (name, written) in [("tick", Some(tick)), ("zero", Some(zero)), ("untimed", None)] { + let info = + moq_net::track::Info::default().with_timescale(written.map(|_| moq_net::Timescale::new(90_000).unwrap())); + let create = |name: &str| -> u32 { + let mut state = State::lock(); + state + .publish + .track(Id::try_from(broadcast).unwrap(), name, Some(info.clone())) + .unwrap() + .into() + }; + let track = create(name); + let json_name = format!("{name}.json"); + let json_track = create(&json_name); - let consume = request_broadcast(origin, path); - let frame_cb = Callback::new(); - let consumer = id(unsafe { - moq_consume_track( - consume, - track_name.as_ptr() as *const c_char, - track_name.len(), - std::ptr::null(), - Some(channel_callback), - frame_cb.ptr, - ) - }); + let frames = Callback::new(); + let frame_consumer = id(unsafe { + moq_consume_track( + consume, + name.as_ptr().cast(), + name.len(), + std::ptr::null(), + Some(channel_callback), + frames.ptr, + ) + }); + let datagrams = Callback::new(); + let datagram_consumer = id(unsafe { + moq_consume_datagrams( + consume, + name.as_ptr().cast(), + name.len(), + Some(channel_callback), + datagrams.ptr, + ) + }); + let values = Callback::new(); + let value_consumer = id(unsafe { + moq_consume_json_stream( + consume, + json_name.as_ptr().cast(), + json_name.len(), + Some(channel_callback), + values.ptr, + ) + }); - State::lock() - .publish - .track_producer(track) - .unwrap() - .write_frame(None, &b"untimed"[..]) + let timestamp = written.as_ref().map_or(std::ptr::null(), std::ptr::from_ref); + let payload = b"payload"; + assert_eq!( + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), timestamp) }, + 0 + ); + let frame_id = id(frames.recv()); + let mut frame = moq_frame { + payload: std::ptr::null(), + payload_size: 0, + timestamp: &tick, + keyframe: false, + }; + assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); + assert_eq!(read_timestamp(frame.timestamp), written, "{name} frame"); + assert_eq!(moq_consume_track_frame_free(frame_id), 0); + + // The datagram subscription is live once the frame arrived on the same track. + assert_eq!( + unsafe { + moq_publish_track_datagram(track, payload.as_ptr(), payload.len(), timestamp, std::ptr::null_mut()) + }, + 0 + ); + let datagram_id = id(datagrams.recv()); + let mut datagram = moq_datagram { + payload: std::ptr::null(), + payload_size: 0, + timestamp: &tick, + sequence: 0, + }; + assert_eq!(unsafe { moq_consume_datagram(datagram_id, &mut datagram) }, 0); + assert_eq!(read_timestamp(datagram.timestamp), written, "{name} datagram"); + assert_eq!(moq_consume_datagram_free(datagram_id), 0); + + let producer = State::lock() + .publish + .track_producer(Id::try_from(json_track).unwrap()) + .unwrap() + .clone(); + let mut json = moq_json::stream::Producer::::new(producer, Default::default()); + json.append(moq_net::Timed { + value: &serde_json::json!(1), + at: written.map(|written| written.try_into().unwrap()), + }) .unwrap(); - let frame_id = id(frame_cb.recv()); - let mut frame = moq_frame { - payload: std::ptr::null(), - payload_size: 0, - timestamp_us: 7, - timestamp_present: true, - keyframe: false, - }; - assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); - assert!(!frame.timestamp_present, "an untimed frame reads untimed"); - assert_eq!(frame.timestamp_us, 0); - assert_eq!(moq_consume_track_frame_free(frame_id), 0); + let value_id = id(values.recv()); + let mut value = moq_json_value { + json: std::ptr::null(), + json_len: 0, + timestamp: &tick, + }; + assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); + assert_eq!(read_timestamp(value.timestamp), written, "{name} JSON value"); + assert_eq!(moq_consume_json_value_free(value_id), 0); + + assert_eq!(moq_consume_track_cancel(frame_consumer), 0); + assert_eq!(frames.recv_terminal(), 0); + assert_eq!(moq_consume_datagrams_cancel(datagram_consumer), 0); + assert_eq!(datagrams.recv_terminal(), 0); + assert_eq!(moq_consume_json_cancel(value_consumer), 0); + assert_eq!(values.recv_terminal(), 0); + } - assert_eq!(moq_consume_track_cancel(consumer), 0); - assert_eq!(frame_cb.recv_terminal(), 0, "clean close delivers terminal 0"); assert_eq!(moq_consume_close(consume), 0); assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_origin_close(origin), 0); } +/// A write refuses a timestamp outside `moq_net::Timestamp`'s range, and an untimed write on a +/// timed track. +#[test] +fn timestamp_writes_refuse_out_of_range_and_mismatch() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"timestamp-refusals"); + let name = b"data"; + let track = + id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), std::ptr::null()) }); + + for invalid in [ + moq_timestamp { value: 0, scale: 0 }, + moq_timestamp { + value: 0, + scale: 1 << 62, + }, + moq_timestamp { + value: 1 << 61, + scale: 1_000_000, + }, + ] { + assert_eq!( + unsafe { moq_publish_track_frame(track, name.as_ptr(), name.len(), &invalid) }, + MOQ_ERROR_TIMESTAMP_OVERFLOW, + "{invalid:?}" + ); + } + assert_eq!( + unsafe { moq_publish_track_frame(track, name.as_ptr(), name.len(), std::ptr::null()) }, + MOQ_ERROR_MOQ + ); + + assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn raw_track_publish_consume() { let origin = id(moq_origin_create()); @@ -1775,7 +1904,7 @@ fn raw_track_publish_consume() { let payload = b"hello raw track"; let timestamp_us = 12_345; assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), timestamp_us) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(timestamp_us)) }, 0 ); @@ -1783,15 +1912,13 @@ fn raw_track_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: true, // should be overwritten with false }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, payload); - assert_eq!(frame.timestamp_us, timestamp_us); - assert!(frame.timestamp_present); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); assert!(!frame.keyframe, "raw frames have no keyframe flag"); assert_eq!(moq_consume_track_frame_free(frame_id), 0); @@ -1800,7 +1927,7 @@ fn raw_track_publish_consume() { let parts: [(&[u8], u64); 2] = [(b"part-0", 20_000), (b"part-1", 30_000)]; for (part, timestamp_us) in parts { assert_eq!( - unsafe { moq_publish_group_frame(group, part.as_ptr(), part.len(), timestamp_us) }, + unsafe { moq_publish_group_frame(group, part.as_ptr(), part.len(), µs(timestamp_us)) }, 0 ); } @@ -1811,14 +1938,13 @@ fn raw_track_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, expected); - assert_eq!(frame.timestamp_us, timestamp_us); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); } @@ -1866,7 +1992,7 @@ fn raw_track_datagram_publish_consume() { let payload = b"hello datagram"; let mut sequence: u64 = u64::MAX; assert_eq!( - unsafe { moq_publish_track_datagram(track, payload.as_ptr(), payload.len(), 120_000, &mut sequence) }, + unsafe { moq_publish_track_datagram(track, payload.as_ptr(), payload.len(), µs(120_000), &mut sequence) }, 0 ); @@ -1874,14 +2000,13 @@ fn raw_track_datagram_publish_consume() { let mut datagram = moq_datagram { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), sequence: 0, }; assert_eq!(unsafe { moq_consume_datagram(dg_id, &mut datagram) }, 0); let received = unsafe { std::slice::from_raw_parts(datagram.payload, datagram.payload_size) }; assert_eq!(received, payload); - assert_eq!(datagram.timestamp_us, 120_000); + assert_eq!(read_timestamp(datagram.timestamp), Some(micros(120_000))); assert_eq!(datagram.sequence, sequence); assert_eq!(moq_consume_datagram_free(dg_id), 0); @@ -1952,7 +2077,7 @@ fn raw_track_subscription_options_and_update() { let payloads: [&[u8]; 3] = [b"zero", b"one", b"two"]; for (i, payload) in payloads.into_iter().enumerate() { assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), i as u64 * 20_000) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(i as u64 * 20_000)) }, 0 ); } @@ -1964,12 +2089,12 @@ fn raw_track_subscription_options_and_update() { start: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 1, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 2, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end_present: true, }]; @@ -1996,14 +2121,13 @@ fn raw_track_subscription_options_and_update() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, b"one"); - assert_eq!(frame.timestamp_us, 20_000); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(20_000))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); let widened = [moq_range { @@ -2023,14 +2147,13 @@ fn raw_track_subscription_options_and_update() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, b"two"); - assert_eq!(frame.timestamp_us, 40_000); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(40_000))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); assert_eq!(moq_consume_track_cancel(consumer), 0); @@ -2065,7 +2188,7 @@ fn raw_track_time_anchor() { let payloads: [&[u8]; 3] = [b"zero", b"one", b"two"]; for (i, payload) in payloads.into_iter().enumerate() { assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), i as u64 * 20_000) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(i as u64 * 20_000)) }, 0 ); } @@ -2077,12 +2200,12 @@ fn raw_track_time_anchor() { start: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_TIME as u32, group: 0, - timestamp_us: 30_000, + timestamp: micros(30_000), }, end: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 0, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end_present: false, }]; @@ -2110,8 +2233,7 @@ fn raw_track_time_anchor() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2176,12 +2298,12 @@ fn raw_track_update_refuses_time_on_untimed() { start: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_TIME as u32, group: 0, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 0, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end_present: false, }]; @@ -2201,8 +2323,7 @@ fn raw_track_update_refuses_time_on_untimed() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2234,14 +2355,14 @@ fn raw_track_relative_update_counts_from_the_track_edge() { }); let publish = |payload: &[u8]| { assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 0) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(0)) }, 0 ); }; let anchor = |kind: moq_anchor_kind, group: u64| moq_anchor { kind: kind as u32, group, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }; let subscribe = |ranges: &[moq_range]| moq_subscription { priority: 0, @@ -2256,8 +2377,7 @@ fn raw_track_relative_update_counts_from_the_track_edge() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2338,24 +2458,30 @@ fn json_snapshot_publish_consume() { ) }); - let mut last_us = 0; + let mut last = 0; for expected in [r#"{"a":1}"#, r#"{"a":2}"#] { assert_eq!( - unsafe { moq_publish_json_snapshot_update(producer, expected.as_ptr() as *const c_char, expected.len()) }, + unsafe { + moq_publish_json_snapshot_update( + producer, + expected.as_ptr() as *const c_char, + expected.len(), + std::ptr::null(), + ) + }, 0 ); let value_id = id(value_cb.recv()); let mut value = moq_json_value { json: std::ptr::null(), json_len: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); // The producer stamps each value with the broadcast clock. - assert!(value.timestamp_present); - assert!(value.timestamp_us >= last_us); - last_us = value.timestamp_us; + let at = read_timestamp(value.timestamp).expect("a stamped value is timed"); + assert!(at.value >= last); + last = at.value; let received = unsafe { std::slice::from_raw_parts(value.json.cast::(), value.json_len) }; assert_eq!( serde_json::from_slice::(received).unwrap(), @@ -2400,24 +2526,30 @@ fn json_stream_publish_consume() { ) }); - let mut last_us = 0; + let mut last = 0; for expected in [r#"{"n":0}"#, r#"{"n":1}"#, r#"{"n":2}"#] { assert_eq!( - unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len()) }, + unsafe { + moq_publish_json_stream_append( + producer, + expected.as_ptr() as *const c_char, + expected.len(), + std::ptr::null(), + ) + }, 0 ); let value_id = id(value_cb.recv()); let mut value = moq_json_value { json: std::ptr::null(), json_len: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); // The producer stamps each value with the broadcast clock. - assert!(value.timestamp_present); - assert!(value.timestamp_us >= last_us); - last_us = value.timestamp_us; + let at = read_timestamp(value.timestamp).expect("a stamped value is timed"); + assert!(at.value >= last); + last = at.value; let received = unsafe { std::slice::from_raw_parts(value.json.cast::(), value.json_len) }; assert_eq!( serde_json::from_slice::(received).unwrap(), @@ -2426,6 +2558,27 @@ fn json_stream_publish_consume() { assert_eq!(moq_consume_json_value_free(value_id), 0); } + // A caller's timestamp replaces the clock's, floored to the track's millisecond scale. + let expected = r#"{"n":3}"#; + let at = moq_timestamp { + value: (last + 1_000) * 90 + 45, + scale: 90_000, + }; + assert_eq!( + unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len(), &at) }, + 0 + ); + let value_id = id(value_cb.recv()); + let mut value = moq_json_value { + json: std::ptr::null(), + json_len: 0, + timestamp: std::ptr::null(), + }; + assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); + let read = read_timestamp(value.timestamp).expect("a stamped value is timed"); + assert_eq!((read.value, read.scale), (last + 1_000, 1_000)); + assert_eq!(moq_consume_json_value_free(value_id), 0); + assert_eq!(moq_consume_json_cancel(consumer), 0); assert_eq!(value_cb.recv_terminal(), 0, "clean close delivers terminal 0"); assert!(moq_consume_json_cancel(consumer) < 0, "double-close should fail"); @@ -2442,7 +2595,7 @@ type WindowEvent = ( moq_json_window_kind, std::ops::Range, Option, - Option, + Option, ); /// Read and free the next event delivered to a JSON window consumer. @@ -2454,15 +2607,14 @@ fn recv_window(cb: &Callback) -> WindowEvent { end: 0, json: std::ptr::null(), json_len: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_window_event(event_id, &mut event) }, 0); let json = (!event.json.is_null()).then(|| { let json = unsafe { std::slice::from_raw_parts(event.json.cast::(), event.json_len) }; serde_json::from_slice(json).unwrap() }); - let timestamp = event.timestamp_present.then_some(event.timestamp_us); + let timestamp = read_timestamp(event.timestamp).map(|timestamp| timestamp.try_into().unwrap()); assert_eq!(moq_consume_json_window_event_free(event_id), 0); assert!( moq_consume_json_window_event_free(event_id) < 0, @@ -2519,7 +2671,7 @@ fn json_window_publish_consume() { } assert_eq!(moq_publish_json_window_pop(producer, 2), 0); - let mut last_us = 0; + let mut last = moq_net::Timestamp::ZERO; for n in 0..3 { let (kind, range, json, timestamp) = recv_window(&event_cb); assert_eq!( @@ -2527,12 +2679,12 @@ fn json_window_publish_consume() { (MOQ_JSON_WINDOW_KIND_PUSH, n..n + 1, Some(serde_json::json!({ "n": n }))) ); let timestamp = timestamp.expect("the producer stamps each edit with the broadcast clock"); - assert!(timestamp >= last_us); - last_us = timestamp; + assert!(timestamp >= last); + last = timestamp; } let (kind, range, json, timestamp) = recv_window(&event_cb); assert_eq!((kind, range, json), (MOQ_JSON_WINDOW_KIND_POP, 0..2, None)); - assert!(timestamp.expect("the pop is stamped too") >= last_us); + assert!(timestamp.expect("the pop is stamped too") >= last); // Closing the broadcast ends the open window and releases its handle. assert_eq!(moq_publish_close(broadcast), 0); @@ -2584,8 +2736,7 @@ fn json_window_refreshes_a_bounded_checkpoint() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2704,7 +2855,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) }); let payload = b"tail"; assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 1_000) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(1_000)) }, 0 ); assert_eq!(moq_publish_track_finish(track), 0); @@ -2717,7 +2868,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { )); let frame = b"opus frame"; assert_eq!( - unsafe { moq_publish_media_frame(media, frame.as_ptr(), frame.len(), 1_000) }, + unsafe { moq_publish_media_frame(media, frame.as_ptr(), frame.len(), micros(1_000)) }, 0 ); assert_eq!(moq_publish_media_finish(media), 0); @@ -2748,8 +2899,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2839,7 +2989,7 @@ fn double_close_all_resource_types() { let payload = b"test"; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 1_000_000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(1_000_000)) }, 0 ); let frame_id = id(frame_cb.recv()); @@ -2878,7 +3028,7 @@ fn media_cut_bounds_audio_groups() { let payload = b"test"; for i in 0..3u64 { assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), i * 20_000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(i * 20_000)) }, 0 ); assert_eq!(moq_publish_media_cut(media), 0, "each packet is its own group"); @@ -2886,7 +3036,7 @@ fn media_cut_bounds_audio_groups() { // The same boundary, with the next group explicitly numbered. assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 60_000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(60_000)) }, 0 ); assert_eq!(moq_publish_media_seek(media, 42), 0); @@ -3452,7 +3602,7 @@ fn track_demand_reports_the_wanted_group() { let group = id(moq_publish_track_group(track)); for timestamp_us in [0, 1_000] { assert_eq!( - unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), timestamp_us) }, + unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), µs(timestamp_us)) }, 0 ); } @@ -3611,15 +3761,14 @@ fn dynamic_serves_track_requests() { let payload = b"hello dynamic track"; assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 42) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(42)) }, 0 ); let frame_id = id(frame_cb.recv()); let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -3627,7 +3776,7 @@ fn dynamic_serves_track_requests() { unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, payload ); - assert_eq!(frame.timestamp_us, 42); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(42))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); // A second request is aborted, and its subscriber sees the application code. @@ -3707,7 +3856,7 @@ fn dynamic_track_request_publishes_media() { let payload = b"opus frame"; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 1000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(1000)) }, 0 ); let frame_id = id(frame_cb.recv()); @@ -3806,7 +3955,7 @@ fn track_dynamic_serves_a_fetch_miss() { assert!(moq_group_request_free(request) < 0, "accept consumes the request"); let payload = b"fetched"; assert_eq!( - unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), 100_000) }, + unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), µs(100_000)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -3936,7 +4085,7 @@ fn a_rejected_group_request_binds_only_its_readers() { let group = id(moq_group_request_accept(request)); let payload = b"fetched"; assert_eq!( - unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), 6_000) }, + unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), µs(6_000)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -3974,7 +4123,7 @@ fn track_request_dynamic_survives_accept() { let group = id(moq_group_request_accept(group_request)); let payload = b"archive"; assert_eq!( - unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), 180_000) }, + unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), µs(180_000)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -4055,7 +4204,7 @@ fn local_publish_consume() { let payload = b"opus audio payload data"; let timestamp_us: u64 = 1_000_000; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), timestamp_us) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(timestamp_us)) }, 0 ); @@ -4064,13 +4213,12 @@ fn local_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); assert_eq!(frame.payload_size, payload.len()); - assert_eq!(frame.timestamp_us, timestamp_us); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, payload, "frame payload should match"); @@ -4221,7 +4369,7 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { let payload = b"opus audio payload data"; let timestamp_us: u64 = 1_000_000; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), timestamp_us) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(timestamp_us)) }, 0 ); @@ -4229,14 +4377,13 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, payload, "the sibling broadcast's frame should arrive"); - assert_eq!(frame.timestamp_us, timestamp_us); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); assert_eq!(moq_consume_read_free(frame_id), 0); assert_eq!(moq_consume_audio_cancel(track), 0); @@ -4680,7 +4827,7 @@ fn video_publish_consume() { let keyframe = [0x00, 0x00, 0x00, 0x01, 0x65, 0xAA, 0xBB, 0xCC]; assert_eq!( - unsafe { moq_publish_media_frame(media, keyframe.as_ptr(), keyframe.len(), 0) }, + unsafe { moq_publish_media_frame(media, keyframe.as_ptr(), keyframe.len(), micros(0)) }, 0 ); @@ -4688,12 +4835,11 @@ fn video_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); - assert_eq!(frame.timestamp_us, 0); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(0))); assert!(frame.payload_size > 0, "frame should have payload data"); assert_eq!(moq_consume_read_free(frame_id), 0); @@ -4746,7 +4892,7 @@ fn audio_raw_publish() { let samples = vec![0.0f32; 960 * 2]; let pcm = unsafe { std::slice::from_raw_parts(samples.as_ptr().cast::(), std::mem::size_of_val(&samples[..])) }; let frame = moq_audio_frame { - timestamp_us: 0, + timestamp: micros(0), data: pcm.as_ptr(), data_size: pcm.len(), }; @@ -4804,7 +4950,7 @@ fn audio_raw_publish_frame_durations() { let samples = vec![0.0f32; 120 * 2]; let pcm = unsafe { std::slice::from_raw_parts(samples.as_ptr().cast::(), std::mem::size_of_val(&samples[..])) }; let frame = moq_audio_frame { - timestamp_us: 0, + timestamp: micros(0), data: pcm.as_ptr(), data_size: pcm.len(), }; @@ -4854,7 +5000,7 @@ fn audio_raw_decode_reads_the_encoder_end() { .flat_map(|i| (i as f32 / SAMPLES as f32).to_le_bytes()) .collect(); let frame = moq_audio_frame { - timestamp_us: START_US, + timestamp: micros(START_US), data: pcm.as_ptr(), data_size: pcm.len(), }; @@ -4889,12 +5035,12 @@ fn audio_raw_decode_reads_the_encoder_end() { let mut read = moq_audio_read { kind: moq_decode_read_kind::MOQ_DECODE_READ_GAP, frame: moq_audio_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), data: std::ptr::null(), data_size: 0, }, gap: moq_decode_gap::default(), - end_us: 0, + end: moq_timestamp::default(), }; assert_eq!(unsafe { moq_decode_audio_read(id(code), &mut read) }, 0); match read.kind { @@ -4904,14 +5050,14 @@ fn audio_raw_decode_reads_the_encoder_end() { } moq_decode_read_kind::MOQ_DECODE_READ_END => { assert!(read.frame.data.is_null(), "an end carries no samples"); - ends.push(read.end_us); + ends.push(read.end); } moq_decode_read_kind::MOQ_DECODE_READ_GAP => panic!("nothing was lost"), } assert_eq!(moq_decode_audio_read_free(id(code)), 0); } assert!(frames > 0, "a finished track decodes from its start"); - assert_eq!(ends, [START_US + SAMPLES as u64 * 1_000_000 / 48_000]); + assert_eq!(ends, [micros(START_US + SAMPLES as u64 * 1_000_000 / 48_000)]); assert_eq!(moq_consume_catalog_free(catalog_id), 0); assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); @@ -4954,7 +5100,7 @@ fn video_raw_publish_consume() { let rgba = gray_rgba(320, 240); let publish = |index: u64| { let frame = moq_video_encoder_frame { - timestamp_us: index * 1_001_000 / 30, + timestamp: micros(index * 1_001_000 / 30), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -5135,7 +5281,7 @@ fn decode_first_frame(output: &moq_video_decoder_output) -> (u32, u32, usize) { let rgba = gray_rgba(320, 240); let publish = |index: u64| { let frame = moq_video_encoder_frame { - timestamp_us: index * 33_333, + timestamp: micros(index * 33_333), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -5260,7 +5406,7 @@ fn video_raw_publish_from_many_threads() { assert_eq!(moq_encode_video_cut(producer), 0); } let frame = moq_video_encoder_frame { - timestamp_us: i * 33_333, + timestamp: micros(i * 33_333), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -5283,7 +5429,7 @@ fn video_raw_publish_from_many_threads() { /// Publish one mid-gray frame to a raw video producer, returning the status code. fn publish_gray(producer: u32, rgba: &[u8]) -> i32 { let frame = moq_video_encoder_frame { - timestamp_us: 0, + timestamp: micros(0), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -5460,7 +5606,7 @@ fn video_raw_publish_rejects_frame_size_mismatch() { // of its own, so this is caught as a wrong-sized picture. let rgba = gray_rgba(640, 480); let frame = moq_video_encoder_frame { - timestamp_us: 0, + timestamp: micros(0), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -5630,7 +5776,14 @@ fn video_raw_decode() { for (i, frame) in frames.iter().enumerate() { assert_eq!( - unsafe { moq_publish_media_frame(media, frame.payload.as_ptr(), frame.payload.len(), (i as u64) * 33_000) }, + unsafe { + moq_publish_media_frame( + media, + frame.payload.as_ptr(), + frame.payload.len(), + micros((i as u64) * 33_000), + ) + }, 0 ); } @@ -5697,7 +5850,7 @@ fn multiple_frames_ordering() { for (i, &ts) in timestamps.iter().enumerate() { let payload = format!("frame-{i}"); assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), ts) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(ts)) }, 0 ); } @@ -5707,12 +5860,15 @@ fn multiple_frames_ordering() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); - assert_eq!(frame.timestamp_us, expected_ts, "frame {i} has wrong timestamp"); + assert_eq!( + read_timestamp(frame.timestamp), + Some(micros(expected_ts)), + "frame {i} has wrong timestamp" + ); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; let expected = format!("frame-{i}"); @@ -6780,13 +6936,13 @@ fn server_accepts_a_session() { let (consumer, frames) = subscribe_named_track(consumed, b"tail"); let first = b"ready"; assert_eq!( - unsafe { moq_publish_track_frame(track, first.as_ptr(), first.len(), 0) }, + unsafe { moq_publish_track_frame(track, first.as_ptr(), first.len(), µs(0)) }, 0 ); assert_eq!(moq_consume_track_frame_free(id(frames.recv())), 0); let tail = vec![42; 64 * 1024]; assert_eq!( - unsafe { moq_publish_track_frame(track, tail.as_ptr(), tail.len(), 1) }, + unsafe { moq_publish_track_frame(track, tail.as_ptr(), tail.len(), µs(1)) }, 0 ); assert_eq!(moq_publish_track_finish(track), 0); @@ -7049,7 +7205,7 @@ fn write_opus(media: u32, start_us: u64, count: u64, size: usize) { for i in 0..count { let ts = start_us + i * 20_000; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), ts) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(ts)) }, 0 ); assert_eq!(moq_publish_media_cut(media), 0); @@ -7379,7 +7535,7 @@ fn group_duration_hint_lists_hls_up_front() { let payload = [0u8; 100]; for i in 0..20u64 { assert_eq!( - unsafe { moq_publish_media_frame(hinted, payload.as_ptr(), payload.len(), i * 20_000) }, + unsafe { moq_publish_media_frame(hinted, payload.as_ptr(), payload.len(), micros(i * 20_000)) }, 0 ); if i % 5 == 4 { diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index 0076486281a..99ba0c12a73 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -20,7 +20,9 @@ use tokio::sync::oneshot; use crate::decode::Read; use crate::ffi::OnStatus; use crate::task::Task; -use crate::{Error, Id, NonZeroSlab, Shared, State, ffi, moq_decode_gap, moq_decode_read_kind, moq_decode_start}; +use crate::{ + Error, Id, NonZeroSlab, Shared, State, ffi, moq_decode_gap, moq_decode_read_kind, moq_decode_start, moq_timestamp, +}; // ---- C-visible types ---- @@ -146,8 +148,8 @@ pub struct moq_video_encode_options { /// dimensions, since there they are what the stream turned out to be. #[repr(C)] pub struct moq_video_encoder_frame { - /// Presentation timestamp, in microseconds. - pub timestamp_us: u64, + /// The presentation timestamp. + pub timestamp: moq_timestamp, /// The raw frame bytes in the configured layout. pub data: *const u8, /// The length in bytes of `data`. @@ -201,8 +203,8 @@ pub struct moq_video_decoder_output { /// dimensions because the encoder already fixed them. #[repr(C)] pub struct moq_video_frame { - /// The presentation timestamp in microseconds. - pub timestamp_us: u64, + /// The presentation timestamp. + pub timestamp: moq_timestamp, /// The decoded width in pixels. pub width: u32, /// The decoded height in pixels. @@ -224,10 +226,10 @@ pub struct moq_video_read { /// The lost span, for [moq_decode_read_kind::MOQ_DECODE_READ_GAP]. Every picture from /// before the loss precedes it, and what follows does not continue what came before. pub gap: moq_decode_gap, - /// Where the stopped encoder's media stops in microseconds, for + /// Where the stopped encoder's media stops, for /// [moq_decode_read_kind::MOQ_DECODE_READ_END]. The stopped encoder's last pictures /// precede it; what follows comes from a fresh encoder. - pub end_us: u64, + pub end: moq_timestamp, } // ---- State extension (used internally by lib.rs) ---- @@ -540,7 +542,7 @@ fn follow_grant(shared: &Shared) -> Result<(), Error> { impl VideoEncoder { /// Encode and publish one picture, returning whether it moved the rendition to a new track. - fn publish_frame(&mut self, timestamp_us: u64, data: &[u8]) -> Result { + fn publish_frame(&mut self, timestamp: moq_net::Timestamp, data: &[u8]) -> Result { if let Some(followed) = &self.followed { followed.check()?; } @@ -558,7 +560,7 @@ impl VideoEncoder { let Some(encoder) = self.encoder.as_mut() else { return Ok(false); }; - let frame = moq_video::Frame::new(surface, moq_net::Timestamp::from_micros(timestamp_us)?); + let frame = moq_video::Frame::new(surface, timestamp); // A backend that pipelines hands back an earlier frame's output, so this is // zero or more access units rather than one per call. let encoded = block_on(encoder.encode(frame))?; @@ -835,7 +837,7 @@ impl Video { pixels: OnceLock::new(), })), Some(moq_video::decode::Read::Gap { timestamp, duration }) => Read::gap(timestamp, duration)?, - Some(moq_video::decode::Read::End { end }) => Read::end(end)?, + Some(moq_video::decode::Read::End { end }) => Read::end(end), None => return Ok(()), }, }; @@ -1069,7 +1071,7 @@ pub unsafe extern "C" fn moq_encode_video_frame(producer: u32, frame: *const moq .lock() .as_mut() .ok_or(Error::MediaNotFound)? - .publish_frame(frame.timestamp_us, data)?; + .publish_frame(frame.timestamp.try_into()?, data)?; // The follower takes the encoder's lock, so it moves with the track after the encode. match moved { true => crate::video::follow_grant(&producer), @@ -1257,13 +1259,12 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read let id = ffi::parse_id(id)?; let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; let read = State::lock().video.read(id)?; - let (kind, gap, end_us) = read.info(); + let (kind, gap, end) = read.info(); let frame = match &read { Read::Frame(frame) => { let pixels = frame.pixels()?; moq_video_frame { - // The decoded Timestamp is bounded by a QUIC varint, so its microseconds fit. - timestamp_us: frame.frame.timestamp.as_micros() as u64, + timestamp: frame.frame.timestamp.into(), width: pixels.width, height: pixels.height, // The slab keeps its `Arc` until the id is freed, and the pixels are @@ -1273,19 +1274,14 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read } } _ => moq_video_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), width: 0, height: 0, data: std::ptr::null(), data_size: 0, }, }; - *dst = moq_video_read { - kind, - frame, - gap, - end_us, - }; + *dst = moq_video_read { kind, frame, gap, end }; Ok(()) }) } @@ -1357,7 +1353,14 @@ mod tests { follow_grant(&shared).unwrap(); let before = shared.lock().as_ref().unwrap().reservation.clone().unwrap(); let small = vec![0x80; 320 * 240 * 4]; - assert!(!shared.lock().as_mut().unwrap().publish_frame(0, &small).unwrap()); + assert!( + !shared + .lock() + .as_mut() + .unwrap() + .publish_frame(moq_net::Timestamp::ZERO, &small) + .unwrap() + ); // Disabled, then resumed onto the larger picture. { @@ -1370,7 +1373,12 @@ mod tests { .unwrap(); } let large = vec![0x80; 640 * 480 * 4]; - let moved = shared.lock().as_mut().unwrap().publish_frame(66_666, &large).unwrap(); + let moved = shared + .lock() + .as_mut() + .unwrap() + .publish_frame(moq_net::Timestamp::from_micros(66_666).unwrap(), &large) + .unwrap(); assert!(moved, "the larger picture is a new codec string"); follow_grant(&shared).unwrap(); let guard = shared.lock(); diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index f0cd65ff311..bf1913b453f 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -14,6 +14,7 @@ use crate::consumer::MoqBroadcastConsumer; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Task; +use crate::media::MoqTimestamp; /// Raw PCM sample format, mirroring WebCodecs `AudioData.format`. /// @@ -193,8 +194,8 @@ pub struct MoqAudioDecoderOutput { /// PCM in the configured `output_format`. #[derive(uniffi::Record)] pub struct MoqAudioFrame { - /// Presentation timestamp of the first sample, in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp of the first sample. + pub timestamp: MoqTimestamp, /// The samples, in the configured PCM layout. pub data: Vec, } @@ -215,36 +216,31 @@ pub enum MoqAudioRead { /// or a packet's timestamp did not continue the previous one. What follows does not /// continue what came before. Gap { - /// The furthest presentation point already read, in microseconds. - timestamp_us: u64, + /// The furthest presentation point already read. + timestamp: MoqTimestamp, /// An upper bound on how long until the next frame resumes. duration: Duration, }, /// The publisher stopped its encoder: it paused, switched source, or finished. /// - /// Frames that follow and start before `end_us` are the stopped encoder's remaining + /// Frames that follow and start before `end` are the stopped encoder's remaining /// media; the first frame at or past it comes from a fresh encoder. End { - /// Where the stopped encoder's media stops, in microseconds. - end_us: u64, + /// Where the stopped encoder's media stops. + end: MoqTimestamp, }, } -impl TryFrom for MoqAudioRead { - type Error = MoqError; - - fn try_from(read: moq_audio::decode::Read) -> Result { - use crate::consumer::timestamp_us; - Ok(match read { +impl From for MoqAudioRead { + fn from(read: moq_audio::decode::Read) -> Self { + match read { moq_audio::decode::Read::Frame(frame) => Self::Frame { frame: frame.into() }, moq_audio::decode::Read::Gap { timestamp, duration } => Self::Gap { - timestamp_us: timestamp_us(timestamp)?, + timestamp: timestamp.into(), duration: crate::ffi::duration(duration.into()), }, - moq_audio::decode::Read::End { end } => Self::End { - end_us: timestamp_us(end)?, - }, - }) + moq_audio::decode::Read::End { end } => Self::End { end: end.into() }, + } } } @@ -362,11 +358,7 @@ impl MoqAudioEncoder { impl From for MoqAudioFrame { fn from(f: moq_audio::Frame) -> Self { Self { - // The binding surface carries plain microseconds, so flatten the - // scaled `Timestamp` here. Saturating rather than erroring: this is a - // frame we already decoded, and a u64 overflow needs a timestamp - // ~580,000 years out. - timestamp_us: u64::try_from(f.timestamp.as_micros()).unwrap_or(u64::MAX), + timestamp: f.timestamp.into(), data: f.data.to_vec(), } } @@ -376,10 +368,7 @@ impl TryFrom for moq_audio::Frame { type Error = moq_audio::Error; fn try_from(f: MoqAudioFrame) -> Result { - Ok(Self::new( - f.data.into(), - moq_net::Timestamp::from_micros(f.timestamp_us)?, - )) + Ok(Self::new(f.data.into(), f.timestamp.try_into()?)) } } @@ -570,7 +559,7 @@ impl ConsumerInner { async fn next(&mut self) -> Result, MoqError> { let read = self.consumer.read().await; self.delay.store(nanos(self.consumer.delay()), Ordering::Relaxed); - read?.map(MoqAudioRead::try_from).transpose() + Ok(read?.map(MoqAudioRead::from)) } } @@ -794,7 +783,7 @@ mod tests { // A partial codec frame makes finish publish the final packet and lookahead. audio .write(MoqAudioFrame { - timestamp_us: 0, + timestamp: MoqTimestamp { value: 0, scale: 1 }, data: vec![0.1_f32; 860].into_iter().flat_map(f32::to_ne_bytes).collect(), }) .unwrap(); diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index b2751380a2e..3c05c5af5bb 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -5,7 +5,7 @@ //! runs the same rounds on moq-net, below moq-ffi's handles and runtime. use crate::consumer::MoqTrackConsumer; -use crate::media::MoqFrame; +use crate::media::{MoqFrame, MoqTimestamp}; use crate::origin::{MoqOriginConfig, MoqOriginProducer}; use crate::producer::{MoqBroadcastProducer, MoqTrackInfo, MoqTrackProducer}; @@ -165,7 +165,10 @@ async fn ffi_round( let mut read = Vec::with_capacity(frames); for _ in 0..frames { let frame = group.read_frame().await.unwrap().expect("group ended"); - read.push((frame.payload, frame.timestamp_us)); + let timestamp = frame + .timestamp + .map(|t| moq_net::Timestamp::try_from(t).unwrap().as_micros() as u64); + read.push((frame.payload, timestamp)); } read }) @@ -176,7 +179,10 @@ async fn ffi_round( for f in 0..case.frames() { let frame = MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(n * case.frames() as u64 + f as u64), + timestamp: Some(MoqTimestamp { + value: n * case.frames() as u64 + f as u64, + scale: 1_000_000, + }), }; group.write_frame(frame).unwrap(); } diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index eb0077e77bd..543db83ea1f 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -10,16 +10,11 @@ use crate::ffi::{Background, Guard, Task}; use crate::media::*; use crate::producer::MoqTrackInfo; -pub(crate) fn timestamp_us(timestamp: moq_net::Timestamp) -> Result { - timestamp.as_micros().try_into().map_err(|_| MoqError::TimeOverflow) -} - -fn raw_frame(frame: moq_net::frame::Frame) -> Result { - let timestamp_us = frame.timestamp.map(timestamp_us).transpose()?; - Ok(MoqFrame { +fn raw_frame(frame: moq_net::frame::Frame) -> MoqFrame { + MoqFrame { payload: frame.payload.to_vec(), - timestamp_us, - }) + timestamp: frame.timestamp.map(Into::into), + } } /// Subscriber-side delivery preferences, mirroring [`moq_net::track::Subscription`]. @@ -96,8 +91,8 @@ pub enum MoqAnchor { }, /// The group containing this presentation time. An untimed track refuses it. Time { - /// The presentation time in microseconds. - timestamp_us: u64, + /// The presentation time. + timestamp: MoqTimestamp, }, } @@ -118,9 +113,7 @@ impl TryFrom for moq_net::track::Anchor { Ok(match anchor { MoqAnchor::Absolute { group } => Self::Absolute(group), MoqAnchor::Relative { groups } => Self::Relative(groups), - MoqAnchor::Time { timestamp_us } => { - Self::Time(moq_net::Timestamp::from_micros(timestamp_us).map_err(|_| MoqError::TimeOverflow)?) - } + MoqAnchor::Time { timestamp } => Self::Time(timestamp.try_into()?), }) } } @@ -521,7 +514,7 @@ impl TrackInner { }; Poll::Ready(Ok(Some(MoqDatagram { sequence: datagram.sequence, - timestamp_us: datagram.timestamp.map(timestamp_us).transpose()?, + timestamp: datagram.timestamp.map(Into::into), payload: datagram.payload.to_vec(), }))) } @@ -567,7 +560,7 @@ impl TrackShared { return Ok(None); } if let Some(frame) = kio::wait(|waiter| self.poll(|inner| inner.poll_pending_frame(waiter))).await? { - return Ok(Some(raw_frame(frame)?)); + return Ok(Some(raw_frame(frame))); } } } @@ -769,7 +762,7 @@ struct GroupInner { impl GroupInner { async fn read_frame(&mut self) -> Result, MoqError> { - self.group.read_frame().await?.map(raw_frame).transpose() + Ok(self.group.read_frame().await?.map(raw_frame)) } } diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 8299a70020d..255b7ad0797 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -252,7 +252,7 @@ pub enum MoqError { reason: String, }, - /// A timestamp is outside the supported range. + /// A timestamp value or scale is outside the supported range, or the scale is zero. #[error("timestamp overflow")] TimeOverflow, diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 7efb874fc37..0deb1e44df8 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -11,10 +11,11 @@ use std::sync::Arc; use serde_json::Value; -use crate::consumer::{MoqTrackConsumer, timestamp_us}; +use crate::consumer::MoqTrackConsumer; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Task; +use crate::media::MoqTimestamp; use crate::producer::{Child, MoqBroadcastProducer, MoqTrackProducer}; /// Options for a JSON snapshot producer (lossy latest-value mode). @@ -171,16 +172,16 @@ impl MoqJsonSnapshotProducer { /// Publish a new value, encoded as a snapshot or delta automatically. `value` is a JSON /// document. A no-op if unchanged from the previous update. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn update(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn update(&self, value: String, timestamp: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; producer.update(moq_net::Timed { value: &value, - at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + at: timestamp.map(TryInto::try_into).transpose()?, })?; Ok(()) } @@ -206,10 +207,8 @@ impl MoqJsonSnapshotProducer { pub struct MoqJsonValue { /// The JSON document. pub value: String, - /// The frame's timestamp on the broadcast clock in microseconds, or null when untimed. - /// Rounded down to a whole microsecond, so a tick on a track like 90 kHz may not survive a - /// read and republish exactly. - pub timestamp_us: Option, + /// The frame's timestamp on the broadcast clock, or null when untimed. + pub timestamp: Option, } impl MoqJsonValue { @@ -217,7 +216,7 @@ impl MoqJsonValue { let Some(timed) = timed else { return Ok(None) }; Ok(Some(Self { value: serde_json::to_string(&timed.value)?, - timestamp_us: timed.at.map(timestamp_us).transpose()?, + timestamp: timed.at.map(Into::into), })) } } @@ -325,16 +324,16 @@ impl MoqJsonStreamProducer { } /// Append one record to the log. `value` is a JSON document. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn append(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn append(&self, value: String, timestamp: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; producer.append(moq_net::Timed { value: &value, - at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + at: timestamp.map(TryInto::try_into).transpose()?, })?; Ok(()) } @@ -495,19 +494,19 @@ impl MoqJsonWindowProducer { } /// Append one record to the back of the window. `value` is a JSON document. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn push(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn push(&self, value: String, timestamp: Option) -> Result<(), MoqError> { let value: Value = serde_json::from_str(&value)?; - let at = timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let at = timestamp.map(TryInto::try_into).transpose()?; self.edit(|producer| producer.push(moq_net::Timed { value: &value, at })) } /// Drop `count` records from the front of the window, clamped to what it holds. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn pop(&self, count: u64, timestamp_us: Option) -> Result<(), MoqError> { - let at = timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn pop(&self, count: u64, timestamp: Option) -> Result<(), MoqError> { + let at = timestamp.map(TryInto::try_into).transpose()?; self.edit(|producer| producer.pop(moq_net::Timed { value: count, at })) } @@ -570,10 +569,10 @@ pub enum MoqJsonWindowEvent { pub struct MoqJsonWindowTimed { /// The change to the window. pub event: MoqJsonWindowEvent, - /// The frame's timestamp on the broadcast clock in microseconds, or null when untimed. + /// The frame's timestamp on the broadcast clock, or null when untimed. /// A record first learned of from a group's restatement (after a join, or while behind) /// carries that frame's time, not its original push time. - pub timestamp_us: Option, + pub timestamp: Option, } impl MoqJsonWindowTimed { @@ -602,7 +601,7 @@ impl MoqJsonWindowTimed { }; Ok(Some(Self { event, - timestamp_us: timed.at.map(timestamp_us).transpose()?, + timestamp: timed.at.map(Into::into), })) } } diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 3da7421872b..f1391f0e72e 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -6,9 +6,7 @@ use std::sync::{Arc, Weak}; use bytes::Buf; use moq_mux::catalog::hang::Extra; -use crate::consumer::{ - MoqBroadcastConsumer, MoqFetchGroupOptions, MoqGroupConsumer, MoqSubscription, map_fetch_error, timestamp_us, -}; +use crate::consumer::{MoqBroadcastConsumer, MoqFetchGroupOptions, MoqGroupConsumer, MoqSubscription, map_fetch_error}; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Task; @@ -222,6 +220,35 @@ pub struct MoqAudio { pub jitter: Option, } +/// An exact media timestamp, `value` units at `scale` units per second, mirroring [`moq_net::Timestamp`]. +/// +/// Reads carry the scale the publisher wrote, so a tick such as 90 kHz survives a read and +/// republish exactly. Writing one past the bounds below is refused with [`MoqError::TimeOverflow`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, uniffi::Record)] +pub struct MoqTimestamp { + /// The time in `scale` units, at most `2^61 - 1`. + pub value: u64, + /// Units per second, non-zero and at most `2^62 - 1`. + pub scale: u64, +} + +impl From for MoqTimestamp { + fn from(timestamp: moq_net::Timestamp) -> Self { + Self { + value: timestamp.value(), + scale: timestamp.scale().as_u64(), + } + } +} + +impl TryFrom for moq_net::Timestamp { + type Error = moq_net::TimeOverflow; + + fn try_from(timestamp: MoqTimestamp) -> Result { + Self::from_scale(timestamp.value, timestamp.scale) + } +} + /// A payload and the time it should be presented. /// /// The unit of both writing and raw reading: every producer write takes one of these, and a @@ -231,9 +258,9 @@ pub struct MoqAudio { pub struct MoqFrame { /// The frame payload. pub payload: Vec, - /// Presentation timestamp in microseconds, or null on an untimed track, on both publish and receive. + /// Presentation timestamp, or null on an untimed track, on both publish and receive. #[uniffi(default = None)] - pub timestamp_us: Option, + pub timestamp: Option, } /// A [`MoqFrame`] plus the codec metadata a media track carries. @@ -241,8 +268,8 @@ pub struct MoqFrame { pub struct MoqMediaFrame { /// The frame payload. pub payload: Vec, - /// Presentation timestamp in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp. + pub timestamp: MoqTimestamp, /// Whether this frame opens a group or is a video keyframe; audio is true only at a group start. pub keyframe: bool, } @@ -256,9 +283,9 @@ pub struct MoqDatagram { /// Per-track sequence number, shared with groups. #[uniffi(default = 0)] pub sequence: u64, - /// Presentation timestamp in microseconds, or null on an untimed track, on both publish and receive. + /// Presentation timestamp, or null on an untimed track, on both publish and receive. #[uniffi(default = None)] - pub timestamp_us: Option, + pub timestamp: Option, /// Datagram payload, capped at 1200 bytes. pub payload: Vec, } @@ -756,14 +783,13 @@ impl MoqMediaCatalogProducer { })) } - /// Read the broadcast clock in microseconds, fixing it for subsequent media producers. - pub fn now(&self) -> Result { + /// Read the broadcast clock, fixing it for subsequent media producers. + pub fn now(&self) -> Result { let _guard = crate::ffi::enter(); - self.broadcast.upgrade().ok_or(MoqError::Closed)?.with_state(|state| { - u64::try_from(state.catalog.clock().now().as_micros()).map_err(|_| MoqError::Codec { - reason: "broadcast clock exceeds microsecond timestamp range".into(), - }) - }) + self.broadcast + .upgrade() + .ok_or(MoqError::Closed)? + .with_state(|state| Ok(state.catalog.clock().now().into())) } /// Replace shared video properties, clearing fields that are absent. @@ -1074,10 +1100,12 @@ impl MoqMediaTrackProducer { let mut guard = self.inner.lock().unwrap(); let media = guard.as_mut().ok_or(MoqError::Closed)?; - let timestamp = - hang::container::Timestamp::from_micros(frame.timestamp_us.ok_or_else(|| MoqError::Codec { + let timestamp = frame + .timestamp + .ok_or_else(|| MoqError::Codec { reason: "whole media frames require a timestamp".into(), - })?)?; + })? + .try_into()?; media .import .decode(&frame.payload, Some(timestamp)) @@ -1349,15 +1377,14 @@ pub struct MoqMediaGroupConfig { pub options: Option, } -fn media_frame(mut frame: moq_mux::container::Frame) -> Result { - let timestamp_us = timestamp_us(frame.timestamp)?; +fn media_frame(mut frame: moq_mux::container::Frame) -> MoqMediaFrame { let payload = frame.payload.copy_to_bytes(frame.payload.remaining()).to_vec(); - Ok(MoqMediaFrame { + MoqMediaFrame { payload, - timestamp_us, + timestamp: frame.timestamp.into(), keyframe: frame.keyframe, - }) + } } fn media_container( @@ -1402,37 +1429,32 @@ pub enum MoqMediaRead { }, /// Media after what was already read was lost; what follows does not continue it. Gap { - /// The furthest presentation point already read, in microseconds. - timestamp_us: u64, + /// The furthest presentation point already read. + timestamp: MoqTimestamp, /// An upper bound on how long until the next frame resumes. duration: std::time::Duration, }, /// The publisher stopped its encoder: it paused, switched source, or finished. - /// Frames starting before `end_us` are its remaining media; the first at or past it + /// Frames starting before `end` are its remaining media; the first at or past it /// comes from a fresh encoder. End { - /// Where the stopped encoder's media stops, in microseconds. - end_us: u64, + /// Where the stopped encoder's media stops. + end: MoqTimestamp, }, } -impl TryFrom for MoqMediaRead { - type Error = MoqError; - - fn try_from(read: moq_mux::container::Read) -> Result { - use crate::consumer::timestamp_us; - Ok(match read { +impl From for MoqMediaRead { + fn from(read: moq_mux::container::Read) -> Self { + match read { moq_mux::container::Read::Frame { frame, .. } => Self::Frame { - frame: media_frame(frame)?, + frame: media_frame(frame), }, moq_mux::container::Read::Gap { timestamp, duration } => Self::Gap { - timestamp_us: timestamp_us(timestamp)?, + timestamp: timestamp.into(), duration: crate::ffi::duration(duration.into()), }, - moq_mux::container::Read::End { end, .. } => Self::End { - end_us: timestamp_us(end)?, - }, - }) + moq_mux::container::Read::End { end, .. } => Self::End { end: end.into() }, + } } } @@ -1448,7 +1470,7 @@ struct Media { impl Media { async fn next(&mut self) -> Result, MoqError> { - self.inner.read().await?.map(MoqMediaRead::try_from).transpose() + Ok(self.inner.read().await?.map(MoqMediaRead::from)) } } @@ -1491,6 +1513,10 @@ mod read_tests { .await .unwrap(); let timestamp = |us| moq_net::Timestamp::from_micros(us).unwrap(); + let micros = |value| MoqTimestamp { + value, + scale: 1_000_000, + }; let mut first = track.create_group(0u64.into()).unwrap(); format() .write( @@ -1508,7 +1534,7 @@ mod read_tests { panic!("expected frame") }; assert_eq!(frame.payload, b"encoded"); - assert_eq!(frame.timestamp_us, 10_000); + assert_eq!(frame.timestamp, micros(10_000)); assert!(frame.keyframe); let mut marker = track.create_group(2u64.into()).unwrap(); format() @@ -1524,11 +1550,11 @@ mod read_tests { .unwrap(); marker.finish().unwrap(); assert!( - matches!(reader.next().await.unwrap(), Some(MoqMediaRead::Gap { timestamp_us: 10_000, duration }) if duration == Duration::from_millis(10)) + matches!(reader.next().await.unwrap(), Some(MoqMediaRead::Gap { timestamp, duration }) if timestamp == micros(10_000) && duration == Duration::from_millis(10)) ); assert!(matches!( reader.next().await.unwrap(), - Some(MoqMediaRead::End { end_us: 20_000 }) + Some(MoqMediaRead::End { end }) if end == micros(20_000) )); let mut resumed = track.create_group(3u64.into()).unwrap(); format() @@ -1560,7 +1586,7 @@ struct MediaGroupInner { impl MediaGroupInner { async fn next(&mut self) -> Result, MoqError> { - self.inner.read().await?.map(media_frame).transpose() + Ok(self.inner.read().await?.map(media_frame)) } } diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index db3e02b6c2d..59fe0df5703 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -770,12 +770,12 @@ impl MoqTrackProducer { /// Write `frame` as a single-frame group. /// - /// Custom timescales may round the timestamp during conversion. The frame must + /// A timestamp at another scale than the track's is converted to it, rounding down. The frame must /// match its track's timedness, otherwise it is refused with /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let track = guard.as_mut().ok_or(MoqError::Closed)?; track.write_frame(timestamp, frame.payload)?; @@ -789,7 +789,7 @@ impl MoqTrackProducer { /// its timestamp must match the track's timedness. pub fn append_datagram(&self, frame: MoqFrame) -> Result { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let track = guard.as_mut().ok_or(MoqError::Closed)?; Ok(track.append_datagram(timestamp, frame.payload)?) @@ -803,7 +803,7 @@ impl MoqTrackProducer { /// past a [`finish_at`](Self::finish_at) boundary is refused with `Closed`. pub fn insert_datagram(&self, sequence: u64, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let track = guard.as_mut().ok_or(MoqError::Closed)?; Ok(track.insert_datagram(sequence, timestamp, frame.payload)?) @@ -886,12 +886,12 @@ impl MoqGroupProducer { /// Write `frame` into this group. /// - /// Custom timescales may round the timestamp during conversion. The frame must + /// A timestamp at another scale than the track's is converted to it, rounding down. The frame must /// match its track's timedness, otherwise it is refused with /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let group = guard.as_mut().ok_or(MoqError::Closed)?; group.write_frame(timestamp, frame.payload)?; diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index f68658f3143..419ca4cd434 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -23,6 +23,19 @@ use std::future::Future; use std::sync::Arc; use std::time::Duration; +/// `value` microseconds. +fn us(value: u64) -> MoqTimestamp { + MoqTimestamp { + value, + scale: 1_000_000, + } +} + +/// `timestamp` in whole microseconds, whatever scale it was read at. +fn micros(timestamp: MoqTimestamp) -> u64 { + moq_net::Timestamp::try_from(timestamp).unwrap().as_micros() as u64 +} + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) @@ -592,7 +605,7 @@ async fn raw_audio_activity() { .unwrap(); audio .write(MoqAudioFrame { - timestamp_us: FIRST_TIMESTAMP_US, + timestamp: us(FIRST_TIMESTAMP_US), data: vec![0; FRAME_SAMPLES * std::mem::size_of::()], }) .unwrap(); @@ -601,7 +614,7 @@ async fn raw_audio_activity() { .expect("timed out waiting for raw audio frame") .unwrap() .expect("expected a raw audio frame"); - assert_eq!(first.timestamp_us, FIRST_TIMESTAMP_US); + assert_eq!(micros(first.timestamp), FIRST_TIMESTAMP_US); drop(subscription); kio::clock::timeout(TIMEOUT, audio.demand().unwrap().until_unwanted()) @@ -625,7 +638,7 @@ async fn raw_audio_activity() { audio.reanchor().unwrap(); audio .write(MoqAudioFrame { - timestamp_us: RESUMED_TIMESTAMP_US, + timestamp: us(RESUMED_TIMESTAMP_US), data: vec![0; FRAME_SAMPLES * std::mem::size_of::()], }) .unwrap(); @@ -634,14 +647,14 @@ async fn raw_audio_activity() { .expect("timed out waiting for resumed raw audio frame") .unwrap() .expect("expected a resumed raw audio frame"); - if resumed.timestamp_us == first.timestamp_us { + if resumed.timestamp == first.timestamp { resumed = kio::clock::timeout(TIMEOUT, next_encoded_frame(&subscription)) .await .expect("timed out waiting for re-anchored raw audio frame") .unwrap() .expect("expected a re-anchored raw audio frame"); } - assert_eq!(resumed.timestamp_us, RESUMED_TIMESTAMP_US); + assert_eq!(micros(resumed.timestamp), RESUMED_TIMESTAMP_US); audio.finish().unwrap(); broadcast.close().unwrap(); @@ -723,7 +736,7 @@ async fn audio_subscribes_a_held_disabled_rendition() { for index in 0..4 { audio .write(MoqAudioFrame { - timestamp_us: index * 20_000, + timestamp: us(index * 20_000), data: audio_tone(index as usize * 960, 960, 2), }) .unwrap(); @@ -790,7 +803,7 @@ async fn audio_raw_publish_from_many_threads() { let producer = audio.clone(); std::thread::spawn(move || { producer.write(MoqAudioFrame { - timestamp_us: 250_000 + index * 20_000, + timestamp: us(250_000 + index * 20_000), data: audio_tone(index as usize * 960, 960, 2), }) }) @@ -804,13 +817,20 @@ async fn audio_raw_publish_from_many_threads() { while let Some(read) = kio::clock::timeout(TIMEOUT, decoder.next()).await.unwrap().unwrap() { let frame = match read { MoqAudioRead::Frame { frame } => frame, - MoqAudioRead::End { end_us } => { - assert_eq!(end_us, 250_000 + 8 * 20_000, "the finish ends after the last frame"); + MoqAudioRead::End { end } => { + assert_eq!( + micros(end), + 250_000 + 8 * 20_000, + "the finish ends after the last frame" + ); continue; } MoqAudioRead::Gap { .. } => panic!("nothing was lost"), }; - assert_eq!(frame.timestamp_us, 250_000 + pcm.len() as u64 / 2 * 1_000_000 / 48_000); + assert_eq!( + micros(frame.timestamp), + 250_000 + pcm.len() as u64 / 2 * 1_000_000 / 48_000 + ); pcm.extend(frame.data.as_chunks::<4>().0.iter().map(|s| f32::from_le_bytes(*s))); } assert_eq!(pcm.len(), 8 * 960 * 2, "finish must preserve the entire PCM duration"); @@ -823,7 +843,7 @@ async fn audio_raw_publish_from_many_threads() { } assert!(matches!( audio.write(MoqAudioFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0; 8] }), Err(MoqError::Closed) @@ -862,7 +882,7 @@ async fn audio_raw_publish_rejects_bad_frames() { assert!( audio .write(MoqAudioFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0; size] }) .is_err() @@ -943,7 +963,7 @@ async fn raw_audio_decode_delay() { for i in 0..2 { audio .write(MoqAudioFrame { - timestamp_us: i * FRAME_US, + timestamp: us(i * FRAME_US), data: audio_tone(i as usize * FRAME_SAMPLES, FRAME_SAMPLES, 1), }) .unwrap(); @@ -1035,7 +1055,7 @@ async fn raw_audio_decode_reports_encoder_ends() { } audio .write(MoqAudioFrame { - timestamp_us, + timestamp: us(timestamp_us), data: audio_tone(i * FRAME_SAMPLES, FRAME_SAMPLES, 1), }) .unwrap(); @@ -1046,9 +1066,9 @@ async fn raw_audio_decode_reports_encoder_ends() { let mut frames = Vec::new(); while let Some(read) = kio::clock::timeout(TIMEOUT, decoder.next()).await.unwrap().unwrap() { match read { - MoqAudioRead::Frame { frame } => frames.push((ends.len(), frame.timestamp_us)), + MoqAudioRead::Frame { frame } => frames.push((ends.len(), micros(frame.timestamp))), MoqAudioRead::Gap { .. } => panic!("nothing was lost"), - MoqAudioRead::End { end_us } => ends.push(end_us), + MoqAudioRead::End { end } => ends.push(micros(end)), } } // The reanchor drops whatever the first encoder's lookahead still held, while the @@ -1105,7 +1125,7 @@ async fn raw_audio_frame_durations() { // 2.5 ms of silence at 48 kHz, mono f32: exactly one encoded frame. audio .write(MoqAudioFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0; 120 * std::mem::size_of::()], }) .unwrap(); @@ -1222,7 +1242,7 @@ async fn raw_track_datagram_roundtrip() { let sequence = track .append_datagram(MoqFrame { payload: payload.clone(), - timestamp_us: Some(123_456), + timestamp: Some(us(123_456)), }) .unwrap(); let datagram = kio::clock::timeout(TIMEOUT, consumer.recv_datagram()) @@ -1232,7 +1252,7 @@ async fn raw_track_datagram_roundtrip() { .expect("expected a datagram"); assert_eq!(datagram.sequence, sequence); - assert_eq!(datagram.timestamp_us, Some(123_456)); + assert_eq!(datagram.timestamp.map(micros), Some(123_456)); assert_eq!(datagram.payload, payload); } @@ -1284,7 +1304,7 @@ async fn raw_track_update_does_not_wait_for_pending_read() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); @@ -1295,7 +1315,7 @@ async fn raw_track_update_does_not_wait_for_pending_read() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(20_000)); + assert_eq!(frame.timestamp.map(micros), Some(20_000)); } /// Subscribe to `name` on `broadcast` as a raw track, for a typed consumer to take over. @@ -1310,7 +1330,14 @@ async fn subscribe(broadcast: &MoqBroadcastProducer, name: &str) -> Arc { let producer = MoqJsonStreamProducer::new(&broadcast, &track).unwrap(); producer - .append(String::from_utf8(payload.to_vec()).unwrap(), timestamp_us) + .append(String::from_utf8(payload.to_vec()).unwrap(), timestamp) .unwrap(); producer.finish().unwrap(); } @@ -1348,8 +1375,8 @@ async fn data_writes_preserve_optional_timestamps() { } let frame = consumer.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, payload, "{kind}"); - assert_eq!(frame.timestamp_us, timestamp_us, "{kind}"); - assert_eq!(consumer.info().timescale, timestamp_us.map(|_| 1_000_000)); + assert_eq!(frame.timestamp, timestamp, "{kind}"); + assert_eq!(consumer.info().timescale, timestamp.map(|timestamp| timestamp.scale)); broadcast.close().unwrap(); } } @@ -1367,14 +1394,14 @@ async fn whole_media_frames_require_the_callers_timestamp() { assert!(matches!( media.write_frame(MoqFrame { payload: b"opus frame".to_vec(), - timestamp_us: None + timestamp: None }), Err(MoqError::Codec { .. }) )); media .write_frame(MoqFrame { payload: b"opus frame".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); media.finish().unwrap(); @@ -1397,11 +1424,11 @@ async fn catalog_now_fixes_the_clock_for_later_media() { ) .unwrap(); let now = catalog.now().unwrap(); - assert!(now > 0); + assert!(now.value > 0); media .write_frame(MoqFrame { payload: b"opus frame".to_vec(), - timestamp_us: Some(1_000_000), + timestamp: Some(us(1_000_000)), }) .unwrap(); assert_eq!( @@ -1437,7 +1464,7 @@ async fn json_snapshot_roundtrip() { let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await).unwrap(); for n in 1..=4 { - producer.update(format!(r#"{{"a":{n}}}"#), Some(n * 1000)).unwrap(); + producer.update(format!(r#"{{"a":{n}}}"#), Some(us(n * 1000))).unwrap(); } let value = kio::clock::timeout(TIMEOUT, consumer.next()) @@ -1449,7 +1476,7 @@ async fn json_snapshot_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "a": 1 }) ); - assert_eq!(value.timestamp_us, Some(1000)); + assert_eq!(value.timestamp.map(micros), Some(1000)); let value = kio::clock::timeout(TIMEOUT, consumer.next()) .await @@ -1460,7 +1487,7 @@ async fn json_snapshot_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "a": 2 }) ); - assert_eq!(value.timestamp_us, Some(2000)); + assert_eq!(value.timestamp.map(micros), Some(2000)); // `latest` skips the buffered third state. let value = kio::clock::timeout(TIMEOUT, consumer.latest()) @@ -1472,11 +1499,11 @@ async fn json_snapshot_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "a": 4 }) ); - assert_eq!(value.timestamp_us, Some(4000)); + assert_eq!(value.timestamp.map(micros), Some(4000)); producer.finish().unwrap(); assert!(matches!( - producer.update(r#"{"a":5}"#.into(), Some(5000)), + producer.update(r#"{"a":5}"#.into(), Some(us(5000))), Err(MoqError::Closed) )); let end = kio::clock::timeout(TIMEOUT, consumer.next()) @@ -1615,9 +1642,9 @@ async fn json_window_roundtrip() { let consumer = MoqJsonWindowConsumer::new(&*subscribe(&broadcast, "log").await).unwrap(); for n in 0..3 { - producer.push(format!(r#"{{"n":{n}}}"#), Some(n * 1000)).unwrap(); + producer.push(format!(r#"{{"n":{n}}}"#), Some(us(n * 1000))).unwrap(); } - producer.pop(2, Some(3000)).unwrap(); + producer.pop(2, Some(us(3000))).unwrap(); for n in 0..3 { let event = next_window(&consumer).await.expect("expected a push"); @@ -1625,7 +1652,7 @@ async fn json_window_roundtrip() { event, MoqJsonWindowTimed { event: window_push(n, n), - timestamp_us: Some(n * 1000), + timestamp: Some(us(n * 1000)), } ); } @@ -1633,16 +1660,16 @@ async fn json_window_roundtrip() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event: MoqJsonWindowEvent::Pop { start: 0, end: 2 }, - timestamp_us: Some(3000), + timestamp: Some(us(3000)), }) ); producer.finish().unwrap(); assert!(matches!( - producer.push(r#"{"n":3}"#.into(), Some(4000)), + producer.push(r#"{"n":3}"#.into(), Some(us(4000))), Err(MoqError::Closed) )); - assert!(matches!(producer.pop(1, Some(4000)), Err(MoqError::Closed))); + assert!(matches!(producer.pop(1, Some(us(4000))), Err(MoqError::Closed))); assert_eq!(next_window(&consumer).await, None); } @@ -1672,10 +1699,7 @@ async fn json_window_cut_restates_the_window() { for event in events { assert_eq!( next_window(&consumer).await, - Some(MoqJsonWindowTimed { - event, - timestamp_us: None, - }) + Some(MoqJsonWindowTimed { event, timestamp: None }) ); } @@ -1705,7 +1729,7 @@ async fn json_window_cut_restates_the_window() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event: window_push(3, 3), - timestamp_us: None, + timestamp: None, }) ); @@ -1755,10 +1779,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { for event in events { assert_eq!( next_window(&consumer).await, - Some(MoqJsonWindowTimed { - event, - timestamp_us: None, - }) + Some(MoqJsonWindowTimed { event, timestamp: None }) ); } @@ -1866,7 +1887,7 @@ async fn json_stream_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "n": n }) ); - assert_eq!(value.timestamp_us, None, "an untimed track yields no timestamp"); + assert_eq!(value.timestamp, None, "an untimed track yields no timestamp"); } producer.finish().unwrap(); } @@ -2004,7 +2025,7 @@ async fn dynamic_track_request() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -2021,7 +2042,7 @@ async fn dynamic_track_request() { .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(0)); + assert_eq!(frame.timestamp.map(micros), Some(0)); track.finish().unwrap(); } @@ -2034,33 +2055,33 @@ async fn raw_untimed_frames_and_datagrams_roundtrip() { track .write_frame(MoqFrame { payload: b"frame".to_vec(), - timestamp_us: None, + timestamp: None, }) .unwrap(); let frame = consumer.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, b"frame"); - assert_eq!(frame.timestamp_us, None); + assert_eq!(frame.timestamp, None); let group = track.append_group().unwrap(); let reader = group.consume().unwrap(); group .write_frame(MoqFrame { payload: b"group".to_vec(), - timestamp_us: None, + timestamp: None, }) .unwrap(); group.finish().unwrap(); let frame = reader.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, b"group"); - assert_eq!(frame.timestamp_us, None); + assert_eq!(frame.timestamp, None); track .append_datagram(MoqFrame { payload: b"datagram".to_vec(), - timestamp_us: None, + timestamp: None, }) .unwrap(); let datagram = consumer.recv_datagram().await.unwrap().unwrap(); assert_eq!(datagram.payload, b"datagram"); - assert_eq!(datagram.timestamp_us, None); + assert_eq!(datagram.timestamp, None); track.finish().unwrap(); } @@ -2071,7 +2092,7 @@ fn raw_writes_need_a_timestamp() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let untimed = || MoqFrame { payload: b"ready".to_vec(), - timestamp_us: None, + timestamp: None, }; let refused = |err: MoqError| { matches!( @@ -2100,7 +2121,7 @@ async fn raw_frame_timestamps() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(12_345), + timestamp: Some(us(12_345)), }) .unwrap(); @@ -2110,7 +2131,7 @@ async fn raw_frame_timestamps() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(12_345)); + assert_eq!(frame.timestamp.map(micros), Some(12_345)); let group = track.append_group().unwrap(); let group_consumer = group.consume().unwrap(); @@ -2118,7 +2139,7 @@ async fn raw_frame_timestamps() { group .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(23_456), + timestamp: Some(us(23_456)), }) .unwrap(); group.finish().unwrap(); @@ -2129,11 +2150,91 @@ async fn raw_frame_timestamps() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(23_456)); + assert_eq!(frame.timestamp.map(micros), Some(23_456)); track.finish().unwrap(); } +#[tokio::test] +async fn timestamps_are_exact() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let info = MoqTrackInfo { + timescale: Some(90_000), + ..timed_info() + }; + let track = broadcast.publish_track("video".into(), Some(info)).unwrap(); + let consumer = track.consume(None).unwrap(); + + // A present zero stays present, and one 90 kHz tick reads back as itself rather than + // the 11 µs it floors to. + for value in [0, 1] { + let timestamp = MoqTimestamp { value, scale: 90_000 }; + track + .write_frame(MoqFrame { + payload: b"frame".to_vec(), + timestamp: Some(timestamp), + }) + .unwrap(); + let frame = kio::clock::timeout(TIMEOUT, consumer.read_frame()) + .await + .unwrap() + .unwrap() + .unwrap(); + assert_eq!(frame.timestamp, Some(timestamp)); + } + + // An inserted datagram keeps the exact tick too. + let tick = MoqTimestamp { + value: 1, + scale: 90_000, + }; + track + .insert_datagram( + 7, + MoqFrame { + payload: b"datagram".to_vec(), + timestamp: Some(tick), + }, + ) + .unwrap(); + let datagram = kio::clock::timeout(TIMEOUT, consumer.recv_datagram()) + .await + .unwrap() + .unwrap() + .unwrap(); + assert_eq!(datagram.sequence, 7); + assert_eq!(datagram.timestamp, Some(tick)); + + for invalid in [ + MoqTimestamp { value: 0, scale: 0 }, + MoqTimestamp { + value: 0, + scale: 1 << 62, + }, + MoqTimestamp { + value: 1 << 61, + scale: 90_000, + }, + ] { + let frame = MoqFrame { + payload: b"frame".to_vec(), + timestamp: Some(invalid), + }; + assert!( + matches!(track.write_frame(frame), Err(MoqError::TimeOverflow)), + "{invalid:?}" + ); + let range = MoqRange { + start: MoqAnchor::Time { timestamp: invalid }, + end: None, + }; + assert!(matches!( + moq_net::track::Range::try_from(range), + Err(MoqError::TimeOverflow) + )); + } +} + #[test] fn raw_track_supports_sparse_groups_and_known_end() { let broadcast = MoqBroadcastProducer::new().unwrap(); @@ -2159,7 +2260,7 @@ async fn abort_after_finish_keeps_the_track_handle() { track .write_frame(MoqFrame { payload: b"late abort".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); track.finish().unwrap(); @@ -2177,7 +2278,7 @@ async fn abort_after_finish_reaches_group_consumer() { group .write_frame(MoqFrame { payload: b"late abort".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); group.finish().unwrap(); @@ -2233,13 +2334,13 @@ async fn fetches_cached_group_without_subscribing() { group .write_frame(MoqFrame { payload: b"first".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); group .write_frame(MoqFrame { payload: b"second".to_vec(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); group.finish().unwrap(); @@ -2260,10 +2361,10 @@ async fn fetches_cached_group_without_subscribing() { assert_eq!(fetched.sequence(), 0); let frame = fetched.read_frame().await.unwrap().expect("expected first frame"); assert_eq!(frame.payload, b"first".to_vec()); - assert_eq!(frame.timestamp_us, Some(0)); + assert_eq!(frame.timestamp.map(micros), Some(0)); let frame = fetched.read_frame().await.unwrap().expect("expected second frame"); assert_eq!(frame.payload, b"second".to_vec()); - assert_eq!(frame.timestamp_us, Some(20_000)); + assert_eq!(frame.timestamp.map(micros), Some(20_000)); assert!(fetched.read_frame().await.unwrap().is_none()); } @@ -2312,11 +2413,11 @@ async fn fetches_cached_media_group_and_decodes_container() { assert_eq!(fetched.sequence(), 0); let frame = fetched.next().await.unwrap().expect("expected keyframe"); assert_eq!(frame.payload, b"keyframe"); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); assert!(frame.keyframe); let frame = fetched.next().await.unwrap().expect("expected delta frame"); assert_eq!(frame.payload, b"delta"); - assert_eq!(frame.timestamp_us, 1_020_000); + assert_eq!(micros(frame.timestamp), 1_020_000); assert!(!frame.keyframe); assert!(fetched.next().await.unwrap().is_none()); } @@ -2394,7 +2495,7 @@ async fn fetch_media_group_decodes_multiple_cmaf_samples() { .unwrap() .expect("expected first sample"); assert_eq!(first.payload, b"keyframe"); - assert_eq!(first.timestamp_us, 2_000_000); + assert_eq!(micros(first.timestamp), 2_000_000); assert!(first.keyframe); let second = kio::clock::timeout(TIMEOUT, fetched.next()) .await @@ -2402,7 +2503,7 @@ async fn fetch_media_group_decodes_multiple_cmaf_samples() { .unwrap() .expect("expected second sample"); assert_eq!(second.payload, b"delta"); - assert_eq!(second.timestamp_us, 2_020_000); + assert_eq!(micros(second.timestamp), 2_020_000); assert!(!second.keyframe); assert!( kio::clock::timeout(TIMEOUT, fetched.next()) @@ -2479,7 +2580,7 @@ async fn media_group_decodes_arrival_order_groups() { assert_eq!(first_media.sequence(), 0); let frame = next_media(&first_media).await.unwrap().expect("expected a frame"); assert_eq!(frame.payload, b"a"); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); assert!(frame.keyframe); // A newer group lands while the first is stalled mid-way. @@ -2489,7 +2590,7 @@ async fn media_group_decodes_arrival_order_groups() { assert_eq!(second_media.sequence(), 1); let frame = next_media(&second_media).await.unwrap().expect("expected a frame"); assert_eq!(frame.payload, b"c"); - assert_eq!(frame.timestamp_us, 1_040_000); + assert_eq!(micros(frame.timestamp), 1_040_000); // The stalled group resumes and is still delivered. write_legacy(&mut first, 3, 1_020_000, b"b"); @@ -2498,7 +2599,7 @@ async fn media_group_decodes_arrival_order_groups() { .unwrap() .expect("expected the stalled group's frame"); assert_eq!(frame.payload, b"b"); - assert_eq!(frame.timestamp_us, 1_020_000); + assert_eq!(micros(frame.timestamp), 1_020_000); assert!(!frame.keyframe); first.finish().unwrap(); @@ -2592,7 +2693,7 @@ async fn dynamic_track_serves_fetch_miss_and_priority() { group .write_frame(MoqFrame { payload: b"fetched".to_vec(), - timestamp_us: Some(100_000), + timestamp: Some(us(100_000)), }) .unwrap(); group.finish().unwrap(); @@ -2605,7 +2706,7 @@ async fn dynamic_track_serves_fetch_miss_and_priority() { assert_eq!(fetched.sequence(), 5); let frame = fetched.read_frame().await.unwrap().expect("expected fetched frame"); assert_eq!(frame.payload, b"fetched".to_vec()); - assert_eq!(frame.timestamp_us, Some(100_000)); + assert_eq!(frame.timestamp.map(micros), Some(100_000)); } #[tokio::test] @@ -2738,7 +2839,7 @@ async fn requested_track_dynamic_survives_accept() { group .write_frame(MoqFrame { payload: b"archive".to_vec(), - timestamp_us: Some(180_000), + timestamp: Some(us(180_000)), }) .unwrap(); group.finish().unwrap(); @@ -2750,7 +2851,7 @@ async fn requested_track_dynamic_survives_accept() { .unwrap(); let frame = fetched.read_frame().await.unwrap().expect("expected archive frame"); assert_eq!(frame.payload, b"archive".to_vec()); - assert_eq!(frame.timestamp_us, Some(180_000)); + assert_eq!(frame.timestamp.map(micros), Some(180_000)); } #[tokio::test] @@ -2824,13 +2925,13 @@ async fn video_track_demand_follows_a_new_level() { }; hd.write_frame(MoqFrame { payload: keyframe(0x1f), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); assert_eq!(hd.demand().unwrap().name(), "hd"); hd.write_frame(MoqFrame { payload: keyframe(0x28), - timestamp_us: Some(40_000), + timestamp: Some(us(40_000)), }) .unwrap(); assert_eq!(hd.demand().unwrap().name(), "hd/1"); @@ -2964,7 +3065,7 @@ async fn dynamic_track_request_can_publish_media() { media .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); @@ -2974,7 +3075,7 @@ async fn dynamic_track_request_can_publish_media() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, 20_000); + assert_eq!(micros(frame.timestamp), 20_000); media.discontinuity().unwrap(); media.finish().unwrap(); @@ -3681,7 +3782,7 @@ async fn local_publish_consume_audio() { media .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(1_000_000), + timestamp: Some(us(1_000_000)), }) .unwrap(); @@ -3692,7 +3793,7 @@ async fn local_publish_consume_audio() { .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); broadcast.close().unwrap(); } @@ -3752,7 +3853,7 @@ async fn video_publish_consume() { media .write_frame(MoqFrame { payload: keyframe, - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -3762,7 +3863,7 @@ async fn video_publish_consume() { .unwrap() .expect("expected frame"); - assert_eq!(frame.timestamp_us, 0); + assert_eq!(micros(frame.timestamp), 0); assert!(!frame.payload.is_empty(), "frame should have payload data"); broadcast.close().unwrap(); @@ -3825,7 +3926,7 @@ async fn video_raw_publish_consume() { for i in 0..5u64 { video .write(MoqVideoFrame { - timestamp_us: i * 1_001_000 / 30, + timestamp: us(i * 1_001_000 / 30), data: rgba.clone(), }) .unwrap(); @@ -3875,7 +3976,7 @@ async fn video_raw_publish_consume() { for i in 5..20u64 { video .write(MoqVideoFrame { - timestamp_us: i * 1_001_000 / 30, + timestamp: us(i * 1_001_000 / 30), data: rgba.clone(), }) .unwrap(); @@ -3937,7 +4038,7 @@ async fn video_decode_frame_ownership() { for i in 0..10u64 { video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.clone(), }) .unwrap(); @@ -3985,7 +4086,7 @@ async fn video_decode_frame_ownership() { for i in 10..40u64 { video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.clone(), }) .unwrap(); @@ -4090,7 +4191,7 @@ async fn video_decode_start() { } video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.clone(), }) .unwrap(); @@ -4142,7 +4243,7 @@ async fn video_decode_start() { let mut timestamps = Vec::new(); while let Some(read) = kio::clock::timeout(TIMEOUT, decoder.next()).await.unwrap().unwrap() { match read { - MoqVideoRead::Frame { frame } => timestamps.push(frame.timestamp_us()), + MoqVideoRead::Frame { frame } => timestamps.push(micros(frame.timestamp())), MoqVideoRead::End { .. } => break, MoqVideoRead::Gap { .. } => panic!("nothing was lost"), } @@ -4215,7 +4316,7 @@ async fn video_raw_publish_from_many_threads() { } video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.as_ref().clone(), }) .unwrap(); @@ -4314,7 +4415,7 @@ async fn video_raw_publish_rejects_bad_frames() { assert!( video .write(MoqVideoFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0x80u8; 640 * 480 * 4], }) .is_err() @@ -4323,7 +4424,7 @@ async fn video_raw_publish_rejects_bad_frames() { video.finish().unwrap(); assert!(matches!( video.write(MoqVideoFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0x80u8; 320 * 240 * 4], }), Err(MoqError::Closed) @@ -4376,7 +4477,7 @@ async fn multiple_frames_ordering() { media .write_frame(MoqFrame { payload: payload.into_bytes(), - timestamp_us: Some(ts), + timestamp: Some(us(ts)), }) .unwrap(); } @@ -4388,7 +4489,7 @@ async fn multiple_frames_ordering() { .unwrap() .unwrap_or_else(|| panic!("expected frame {i}")); - assert_eq!(frame.timestamp_us, expected_ts, "frame {i} has wrong timestamp"); + assert_eq!(micros(frame.timestamp), expected_ts, "frame {i} has wrong timestamp"); let expected = format!("frame-{i}"); assert_eq!(frame.payload, expected.as_bytes(), "frame {i} has wrong payload"); } @@ -4487,7 +4588,7 @@ async fn finish_serves_finished_tracks_until_close() { audio .write_frame(MoqFrame { payload: b"tail".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); audio.finish().unwrap(); @@ -4561,7 +4662,7 @@ async fn closing_a_broadcast_ends_its_open_tracks() { let frame = MoqFrame { payload: b"late".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }; assert!(matches!(raw.write_frame(frame.clone()), Err(MoqError::Closed))); assert!(matches!(raw.finish(), Err(MoqError::Closed))); @@ -4796,7 +4897,7 @@ async fn dynamic_broadcast_request() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); @@ -4806,7 +4907,7 @@ async fn dynamic_broadcast_request() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(20_000)); + assert_eq!(frame.timestamp.map(micros), Some(20_000)); track.finish().unwrap(); served.close().unwrap(); @@ -4925,7 +5026,7 @@ async fn raw_track_next_group_is_repeatable() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -4963,7 +5064,7 @@ async fn raw_track_group_order_commits_on_first_read() { track .write_frame(MoqFrame { payload: b"one".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -4981,7 +5082,7 @@ async fn raw_track_group_order_commits_on_first_read() { track .write_frame(MoqFrame { payload: b"two".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); let group = kio::clock::timeout(TIMEOUT, consumer.recv_group()) @@ -4995,7 +5096,7 @@ async fn raw_track_group_order_commits_on_first_read() { let sequence = track .append_datagram(MoqFrame { payload: b"beep".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); let datagram = kio::clock::timeout(TIMEOUT, consumer.recv_datagram()) @@ -5021,14 +5122,14 @@ fn raw_track() -> ( fn datagram_frame(payload: &[u8]) -> MoqFrame { MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(1), + timestamp: Some(us(1)), } } fn group_frame(payload: &[u8]) -> MoqFrame { MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), } } @@ -5111,7 +5212,7 @@ async fn raw_track_insert_datagram_keeps_its_sequence() { .expect("expected a datagram"); assert_eq!(datagram.sequence, 7); assert_eq!(datagram.payload, b"seven".to_vec()); - assert_eq!(datagram.timestamp_us, Some(1)); + assert_eq!(datagram.timestamp.map(micros), Some(1)); assert_eq!(track.append_datagram(datagram_frame(b"next")).unwrap(), 8); } @@ -5372,7 +5473,7 @@ async fn raw_read_frame_skips_empty_group_on_open_track() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(1_000), + timestamp: Some(us(1_000)), }) .unwrap(); @@ -5383,7 +5484,7 @@ async fn raw_read_frame_skips_empty_group_on_open_track() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(1_000)); + assert_eq!(frame.timestamp.map(micros), Some(1_000)); } /// Empty groups already in the cursor are skipped, then the next populated @@ -5401,7 +5502,7 @@ async fn raw_read_frame_skips_empty_then_populated_groups() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(2_000), + timestamp: Some(us(2_000)), }) .unwrap(); @@ -5411,7 +5512,7 @@ async fn raw_read_frame_skips_empty_then_populated_groups() { .unwrap() .expect("expected the populated group's first frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(2_000)); + assert_eq!(frame.timestamp.map(micros), Some(2_000)); } /// A group a hop reset as expired is skipped like an empty one, as a locally expired @@ -5487,7 +5588,7 @@ async fn raw_read_frame_keeps_group_across_cancelled_call() { group .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(3_000), + timestamp: Some(us(3_000)), }) .unwrap(); group.finish().unwrap(); @@ -5499,7 +5600,7 @@ async fn raw_read_frame_keeps_group_across_cancelled_call() { .unwrap() .expect("cancelled read_frame must not lose the group's first frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(3_000)); + assert_eq!(frame.timestamp.map(micros), Some(3_000)); assert!( kio::clock::timeout(TIMEOUT, consumer.read_frame()) @@ -5545,7 +5646,7 @@ async fn raw_read_frame_drops_aborted_pending_group() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(4_000), + timestamp: Some(us(4_000)), }) .unwrap(); let frame = kio::clock::timeout(TIMEOUT, consumer.read_frame()) @@ -5554,7 +5655,7 @@ async fn raw_read_frame_drops_aborted_pending_group() { .unwrap() .expect("an aborted pending group must not block later groups"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(4_000)); + assert_eq!(frame.timestamp.map(micros), Some(4_000)); } /// `next_group` and `read_frame` share one ordered cursor. A cancelled @@ -5571,7 +5672,7 @@ async fn raw_read_frame_and_next_group_share_the_cursor() { first .write_frame(MoqFrame { payload: b"first".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); first.finish().unwrap(); @@ -5591,7 +5692,7 @@ async fn raw_read_frame_and_next_group_share_the_cursor() { track .write_frame(MoqFrame { payload: b"second".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); let frame = kio::clock::timeout(TIMEOUT, consumer.read_frame()) @@ -5709,7 +5810,7 @@ fn without_runtime() { media .write_frame(MoqFrame { payload: b"hello".to_vec(), - timestamp_us: Some(1000), + timestamp: Some(us(1000)), }) .unwrap(); @@ -5837,7 +5938,7 @@ async fn server_client_roundtrip() { media .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(1_000_000), + timestamp: Some(us(1_000_000)), }) .unwrap(); @@ -5847,7 +5948,7 @@ async fn server_client_roundtrip() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); // Clean up. Exercise `shutdown()` on the client side and the underlying // `cancel(code)` on the server side, so both shutdown paths run. @@ -5888,7 +5989,7 @@ async fn roundtrip(media: &MoqMediaTrackProducer, track: &MoqMediaTrackConsumer, media .write_frame(MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(timestamp_us), + timestamp: Some(us(timestamp_us)), }) .unwrap(); loop { @@ -8027,7 +8128,7 @@ async fn shutdown_without_waiter_survives_session_disposal() { let group = track.append_group().unwrap(); group .write_frame(MoqFrame { - timestamp_us: Some(1), + timestamp: Some(us(1)), payload: vec![42; 64 * 1024], }) .unwrap(); @@ -8111,7 +8212,7 @@ async fn shutdown_ready(track: &MoqTrackProducer, reader: &MoqTrackConsumer) { let group = track.append_group().unwrap(); group .write_frame(MoqFrame { - timestamp_us: Some(0), + timestamp: Some(us(0)), payload: b"ready".to_vec(), }) .unwrap(); @@ -8152,7 +8253,7 @@ async fn shutdown_delivers_the_finished_track() { crate::ffi::detached(async move { let group = track.append_group()?; group.write_frame(MoqFrame { - timestamp_us: Some(0), + timestamp: Some(us(0)), payload: b"last".to_vec(), })?; group.finish()?; @@ -8237,7 +8338,7 @@ async fn ascending_subscription_reads_a_cached_backlog_oldest_first() { group .write_frame(MoqFrame { payload: b"x".to_vec(), - timestamp_us: Some(timestamp_us), + timestamp: Some(us(timestamp_us)), }) .unwrap(); group.finish().unwrap(); @@ -8446,7 +8547,7 @@ async fn time_anchors_start_at_the_containing_group() { group .write_frame(MoqFrame { payload: b"x".to_vec(), - timestamp_us: Some(timestamp_us), + timestamp: Some(us(timestamp_us)), }) .unwrap(); group.finish().unwrap(); @@ -8456,7 +8557,9 @@ async fn time_anchors_start_at_the_containing_group() { priority: 0, max_delay: Some(Duration::from_secs(10)), ranges: Some(vec![MoqRange { - start: MoqAnchor::Time { timestamp_us }, + start: MoqAnchor::Time { + timestamp: us(timestamp_us), + }, end: None, }]), order: Some(MoqOrder::Ascending), diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index 6dafb4fc784..0d502e2412e 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -19,6 +19,7 @@ use crate::bandwidth::{MoqAllocator, MoqReservation}; use crate::consumer::MoqBroadcastConsumer; use crate::demand::MoqTrackDemand; use crate::error::MoqError; +use crate::media::MoqTimestamp; /// A CPU pixel layout: what [`MoqVideoProducer::write`] is fed, and what /// [`MoqVideoDecodedFrame::pixels`] converts to. @@ -188,8 +189,8 @@ impl From for moq_video::encode::Gop { /// that layout. #[derive(uniffi::Record)] pub struct MoqVideoFrame { - /// Presentation timestamp, in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp. + pub timestamp: MoqTimestamp, /// The pixels, in the configured layout. pub data: Vec, } @@ -197,8 +198,8 @@ pub struct MoqVideoFrame { /// One access unit emitted by a codec-only video encoder. #[derive(uniffi::Record)] pub struct MoqVideoPacket { - /// Presentation timestamp in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp. + pub timestamp: MoqTimestamp, /// Encoded access-unit payload. pub data: Vec, /// Whether the access unit starts from a keyframe. @@ -209,7 +210,7 @@ fn video_packets(packets: Vec) -> Vec moq_video::Surface::I420(moq_video::I420::new(self.size, frame.data)?), MoqVideoPixelFormat::Rgba => moq_video::Surface::rgba(&frame.data, self.size)?, }; - let frame = moq_video::Frame::new(surface, moq_net::Timestamp::from_micros(frame.timestamp_us)?); + let frame = moq_video::Frame::new(surface, frame.timestamp.try_into()?); let mut guard = self.inner.lock().map_err(|_| panic_error())?; Ok(video_packets(block_on( guard.as_mut().ok_or(MoqError::Closed)?.encode(frame), @@ -420,7 +421,7 @@ impl VideoProducer { let Some(encoder) = self.encoder.as_mut() else { return Ok(()); }; - let frame = moq_video::Frame::new(surface, moq_net::Timestamp::from_micros(frame.timestamp_us)?); + let frame = moq_video::Frame::new(surface, frame.timestamp.try_into()?); // A backend that pipelines hands back an earlier frame's output, so this is // zero or more access units rather than one per call. let encoded = block_on(encoder.encode(frame))?; @@ -1096,10 +1097,9 @@ pub struct MoqVideoDecodedFrame { #[uniffi::export] impl MoqVideoDecodedFrame { - /// Presentation timestamp, in microseconds. - pub fn timestamp_us(&self) -> u64 { - // A decoded Timestamp is bounded by a QUIC varint, so its microseconds fit. - self.frame.timestamp.as_micros() as u64 + /// Presentation timestamp. + pub fn timestamp(&self) -> MoqTimestamp { + self.frame.timestamp.into() } /// Frame width in pixels: what the stream decoded to, since `resize` is only @@ -1163,8 +1163,8 @@ pub enum MoqVideoRead { /// Every picture from before the loss precedes it, and what follows does not continue /// what came before. Gap { - /// The furthest presentation point already read, in microseconds. - timestamp_us: u64, + /// The furthest presentation point already read. + timestamp: MoqTimestamp, /// An upper bound on how long until the next picture resumes. duration: std::time::Duration, }, @@ -1173,28 +1173,23 @@ pub enum MoqVideoRead { /// The stopped encoder's last pictures precede it; what follows comes from a fresh /// encoder. End { - /// Where the stopped encoder's media stops, in microseconds. - end_us: u64, + /// Where the stopped encoder's media stops. + end: MoqTimestamp, }, } -impl TryFrom for MoqVideoRead { - type Error = MoqError; - - fn try_from(read: moq_video::decode::Read) -> Result { - use crate::consumer::timestamp_us; - Ok(match read { +impl From for MoqVideoRead { + fn from(read: moq_video::decode::Read) -> Self { + match read { moq_video::decode::Read::Frame(frame) => Self::Frame { frame: Arc::new(MoqVideoDecodedFrame { frame }), }, moq_video::decode::Read::Gap { timestamp, duration } => Self::Gap { - timestamp_us: timestamp_us(timestamp)?, + timestamp: timestamp.into(), duration: crate::ffi::duration(duration.into()), }, - moq_video::decode::Read::End { end } => Self::End { - end_us: timestamp_us(end)?, - }, - }) + moq_video::decode::Read::End { end } => Self::End { end: end.into() }, + } } } @@ -1204,7 +1199,7 @@ struct VideoConsumerInner { impl VideoConsumerInner { async fn next(&mut self) -> Result, MoqError> { - self.consumer.read().await?.map(MoqVideoRead::try_from).transpose() + Ok(self.consumer.read().await?.map(MoqVideoRead::from)) } } @@ -1447,8 +1442,13 @@ mod finish_tests { }, ) .unwrap(); + // NTSC frame times, which no microsecond count holds exactly. + let ntsc = |i: u64| MoqTimestamp { + value: i * 1001, + scale: 30_000, + }; let picture = |i: u64| MoqVideoFrame { - timestamp_us: i * 1_001_000 / 30, + timestamp: ntsc(i), data: vec![(i * 40) as u8; (width * height * 3 / 2) as usize], }; @@ -1462,9 +1462,9 @@ mod finish_tests { packets.extend(encoder.encode(picture(3)).unwrap()); packets.extend(encoder.finish().unwrap()); - let keyframes: Vec = packets.iter().filter(|p| p.keyframe).map(|p| p.timestamp_us).collect(); + let keyframes: Vec = packets.iter().filter(|p| p.keyframe).map(|p| p.timestamp).collect(); assert_eq!(packets.len(), 4, "one access unit per picture"); - assert_eq!(keyframes, [0, 3 * 1_001_000 / 30], "keyframes at the start and the cut"); + assert_eq!(keyframes, [ntsc(0), ntsc(3)], "keyframes at the start and the cut"); assert!(packets.iter().all(|p| !p.data.is_empty()), "an empty access unit"); assert!(matches!(encoder.encode(picture(4)), Err(MoqError::Closed))); } @@ -1689,7 +1689,10 @@ mod rung_tests { fn frame(i: u64) -> MoqVideoFrame { MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: MoqTimestamp { + value: i * 33_333, + scale: 1_000_000, + }, data: vec![(i * 40) as u8; 320 * 240 * 3 / 2], } } diff --git a/swift/README.md b/swift/README.md index d87418f0d62..1c9c107e9b1 100644 --- a/swift/README.md +++ b/swift/README.md @@ -78,8 +78,8 @@ Every consumer conforms to `AsyncSequence`, so `for try await x in consumer` wor Incoming server `Request` values expose the query-free `path` before acceptance. It is consistent across transports and is empty for the root or missing path. The encoded `query` may contain credentials. -Raw tracks also expose best-effort datagrams: `TrackProducer.appendDatagram(_:timestampUs:)` -returns the assigned sequence number (`insertDatagram(_:sequence:timestampUs:)` takes the +Raw tracks also expose best-effort datagrams: `TrackProducer.appendDatagram(_:timestamp:)` +returns the assigned sequence number (`insertDatagram(_:sequence:timestamp:)` takes the caller's own), `TrackConsumer.recvDatagram()` receives one datagram, and `TrackConsumer.datagrams` streams them in arrival order. Payloads are capped at 1200 bytes. Datagrams require a datagram-capable transport and lite-05 or newer moq-lite, or moq-transport; diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 64608e2b215..4de395ddb1a 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -7,6 +7,8 @@ import MoqFFI // instead (see Client.swift, Broadcast.swift, etc.), so MoqFFI's `Moq`-prefixed // classes never appear in the public API. +/// An exact media timestamp: `value` units at `scale` units per second. +public typealias Timestamp = MoqFFI.MoqTimestamp /// A payload plus the presentation timestamp it should play at. The unit of /// every raw write and raw read. public typealias Frame = MoqFFI.MoqFrame @@ -125,7 +127,7 @@ extension Subscription { /// A span of a track to deliver: from `start` up to `end`, or onward when `end` is `nil`. public typealias Range = MoqFFI.MoqRange /// Where one end of a `Range` falls: `.absolute(group:)`, `.relative(groups:)` - /// back from the latest group, or `.time(timestampUs:)` for the group containing it. + /// back from the latest group, or `.time(timestamp:)` for the group containing it. public typealias Anchor = MoqFFI.MoqAnchor /// Which pending group the publisher sends first: `.ascending` or `.descending`. public typealias Order = MoqFFI.MoqOrder diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index 3e04d6579fb..c4717bb1c89 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -19,20 +19,18 @@ extension Json { public struct Timed { /// The decoded value. public let value: Value - /// The frame's timestamp on the broadcast clock in microseconds, or `nil` when untimed. - /// Rounded down to a whole microsecond, so a tick on a track like 90 kHz may not survive - /// a read and republish exactly. - public let timestampUs: UInt64? + /// The frame's timestamp on the broadcast clock, or `nil` when untimed. + public let timestamp: Timestamp? /// Pair `value` with its frame timestamp. - public init(value: Value, timestampUs: UInt64?) { + public init(value: Value, timestamp: Timestamp?) { self.value = value - self.timestampUs = timestampUs + self.timestamp = timestamp } init?(_ ffi: MoqJsonValue?) throws where Value: Decodable { guard let ffi else { return nil } - self.init(value: try decodeJson(ffi.value), timestampUs: ffi.timestampUs) + self.init(value: try decodeJson(ffi.value), timestamp: ffi.timestamp) } } @@ -63,8 +61,8 @@ extension Json { /// Publish a new value, encoded as a snapshot or merge-patch delta automatically. A no-op /// if unchanged from the previous update. - public func update(_ value: Value, timestampUs: UInt64? = nil) throws { - try ffi.update(value: encodeJson(value), timestampUs: timestampUs) + public func update(_ value: Value, timestamp: Timestamp? = nil) throws { + try ffi.update(value: encodeJson(value), timestamp: timestamp) } /// A watch-only handle to whether the track has subscribers. @@ -131,8 +129,8 @@ extension Json { } /// Append one record to the log. - public func append(_ value: Value, timestampUs: UInt64? = nil) throws { - try ffi.append(value: encodeJson(value), timestampUs: timestampUs) + public func append(_ value: Value, timestamp: Timestamp? = nil) throws { + try ffi.append(value: encodeJson(value), timestamp: timestamp) } /// A watch-only handle to whether the track has subscribers. @@ -202,13 +200,13 @@ extension Json { } /// Append one record to the back of the window. - public func push(_ value: Value, timestampUs: UInt64? = nil) throws { - try ffi.push(value: encodeJson(value), timestampUs: timestampUs) + public func push(_ value: Value, timestamp: Timestamp? = nil) throws { + try ffi.push(value: encodeJson(value), timestamp: timestamp) } /// Drop `count` records from the front of the window, clamped to what it holds. - public func pop(_ count: UInt64, timestampUs: UInt64? = nil) throws { - try ffi.pop(count: count, timestampUs: timestampUs) + public func pop(_ count: UInt64, timestamp: Timestamp? = nil) throws { + try ffi.pop(count: count, timestamp: timestamp) } /// Close the open group, so the next edit opens one restating the retained window. A no-op @@ -263,7 +261,7 @@ extension Json { case .pop(let start, let end): event = .pop(start.. UInt64 { try ffi.now() } + /// Read the broadcast clock, fixing it for subsequent media producers. + public func now() throws -> Timestamp { try ffi.now() } /// Replace the video properties shared by every rendition. public func setVideoProperties(_ properties: VideoProperties) throws { try ffi.setVideoProperties(properties: properties) @@ -251,12 +251,12 @@ public enum Media { TrackDemand(try ffi.demand()) } - /// Write a frame with the given presentation timestamp (microseconds). + /// Write a frame with the given presentation timestamp. /// /// The importer derives keyframe status from the bitstream, so only the payload and its /// timestamp cross the boundary. - public func writeFrame(_ payload: Data, timestampUs: UInt64) throws { - try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) + public func writeFrame(_ payload: Data, timestamp: Timestamp) throws { + try ffi.writeFrame(frame: Frame(payload: payload, timestamp: timestamp)) } /// Mark a timeline break, preserving the advertised jitter and delay. diff --git a/swift/Sources/Moq/Timestamp.swift b/swift/Sources/Moq/Timestamp.swift new file mode 100644 index 00000000000..c5be8733cf4 --- /dev/null +++ b/swift/Sources/Moq/Timestamp.swift @@ -0,0 +1,51 @@ +import MoqFFI + +// The bounds moq-ffi enforces on a write, so a conversion refuses what a write would. +private let maxValue: UInt64 = (1 << 61) - 1 +private let maxScale: UInt64 = (1 << 62) - 1 +private let attosecondsPerSecond: UInt64 = 1_000_000_000_000_000_000 + +@available(macOS 13, iOS 16, *) +extension Timestamp { + /// The timestamp exactly equal to `duration`, at the finest power-of-ten scale that fits. + /// + /// `Duration` counts attoseconds, so the scale starts at 10^18 and steps down one power of ten + /// each time the value would pass `2^61 - 1` (about 2.3 s of attoseconds, 73 years of + /// nanoseconds), down to whole seconds. Throws `MoqError.TimeOverflow` for a negative duration, + /// or one with finer precision than the largest scale whose value fits. + public init(_ duration: Duration) throws { + guard duration >= .zero else { throw MoqError.TimeOverflow } + let (seconds, attoseconds) = duration.components + var scale = attosecondsPerSecond + var divisor: UInt64 = 1 + while scale > 0 { + let (whole, overflow) = UInt64(seconds).multipliedReportingOverflow(by: scale) + let (fraction, remainder) = UInt64(attoseconds).quotientAndRemainder(dividingBy: divisor) + // `fraction` is below `scale`, which is below `maxValue`, so the subtraction can't wrap. + if !overflow, whole <= maxValue - fraction { + // A coarser scale can't hold what this one drops, so stop here either way. + guard remainder == 0 else { throw MoqError.TimeOverflow } + self.init(value: whole + fraction, scale: scale) + return + } + scale /= 10 + divisor *= 10 + } + throw MoqError.TimeOverflow + } + + /// This timestamp as a `Duration`, rounded down to a whole attosecond. + /// + /// Exact when `scale` divides 10^18, such as microseconds or nanoseconds; a 90 kHz tick rounds, + /// so keep the record itself to republish a read exactly. Throws `MoqError.TimeOverflow` for a + /// record outside the bounds a write accepts. + public var duration: Duration { + get throws { + guard scale != 0, scale <= maxScale, value <= maxValue else { throw MoqError.TimeOverflow } + let (seconds, remainder) = value.quotientAndRemainder(dividingBy: scale) + // `remainder` is below `scale`, so the quotient is below 10^18 and fits. + let (attoseconds, _) = scale.dividingFullWidth(remainder.multipliedFullWidth(by: attosecondsPerSecond)) + return Duration(secondsComponent: Int64(seconds), attosecondsComponent: Int64(attoseconds)) + } + } +} diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index 6f2426ecc49..aafee311f61 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -176,23 +176,23 @@ public final class TrackProducer: Sendable { GroupProducer(try ffi.createGroup(sequence: sequence)) } - /// Write a single-frame group with a timestamp in microseconds. - public func writeFrame(_ payload: Data, timestampUs: UInt64? = nil) throws { - try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) + /// Write a single-frame group with a presentation timestamp, or untimed when nil. + public func writeFrame(_ payload: Data, timestamp: Timestamp? = nil) throws { + try ffi.writeFrame(frame: Frame(payload: payload, timestamp: timestamp)) } /// Send a best-effort datagram and return its sequence number. /// - /// `timestampUs` is the presentation timestamp in microseconds. Payloads are + /// `timestamp` is the presentation timestamp, or untimed when nil. Payloads are /// capped at 1200 bytes. There is no stream fallback. - public func appendDatagram(_ payload: Data, timestampUs: UInt64? = nil) throws -> UInt64 { - try ffi.appendDatagram(frame: Frame(payload: payload, timestampUs: timestampUs)) + public func appendDatagram(_ payload: Data, timestamp: Timestamp? = nil) throws -> UInt64 { + try ffi.appendDatagram(frame: Frame(payload: payload, timestamp: timestamp)) } /// Send a best-effort datagram at an explicit sequence number, for a caller that /// allocates its own. `appendDatagram` continues after the largest one. - public func insertDatagram(_ payload: Data, sequence: UInt64, timestampUs: UInt64? = nil) throws { - try ffi.insertDatagram(sequence: sequence, frame: Frame(payload: payload, timestampUs: timestampUs)) + public func insertDatagram(_ payload: Data, sequence: UInt64, timestamp: Timestamp? = nil) throws { + try ffi.insertDatagram(sequence: sequence, frame: Frame(payload: payload, timestamp: timestamp)) } /// The newest group or datagram written, at its newest frame, or `nil` before any. @@ -235,9 +235,9 @@ public final class GroupProducer: Sendable { GroupConsumer(try ffi.consume()) } - /// Write a frame with a timestamp in microseconds. - public func writeFrame(_ payload: Data, timestampUs: UInt64? = nil) throws { - try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) + /// Write a frame with a presentation timestamp, or untimed when nil. + public func writeFrame(_ payload: Data, timestamp: Timestamp? = nil) throws { + try ffi.writeFrame(frame: Frame(payload: payload, timestamp: timestamp)) } /// Mark the group complete. No more frames can be written. diff --git a/swift/Tests/MoqTests/Docs/Prelude.swift b/swift/Tests/MoqTests/Docs/Prelude.swift index f900542855a..a8516215bde 100644 --- a/swift/Tests/MoqTests/Docs/Prelude.swift +++ b/swift/Tests/MoqTests/Docs/Prelude.swift @@ -6,6 +6,6 @@ import Moq var opusInit: Data { fatalError() } var packet: Data { fatalError() } -var pts: UInt64 { fatalError() } +var pts: Timestamp { fatalError() } var rgba: Data { fatalError() } var session: Session { fatalError() } diff --git a/swift/Tests/MoqTests/FfiBench.swift b/swift/Tests/MoqTests/FfiBench.swift index ffa6690c873..205c02660a4 100644 --- a/swift/Tests/MoqTests/FfiBench.swift +++ b/swift/Tests/MoqTests/FfiBench.swift @@ -89,13 +89,17 @@ final class FfiBench: XCTestCase { let received = try await group.readFrame() let frame = try XCTUnwrap(received, "group ended") XCTAssertEqual(frame.payload, payload) - XCTAssertEqual(frame.timestampUs, UInt64(n * c.frames + f)) + XCTAssertEqual( + frame.timestamp, Timestamp(value: UInt64(n * c.frames + f), scale: 1_000_000)) } } } for track in tracks { let group = try track.appendGroup() - for f in 0.. AnnounceEv return try XCTUnwrap(next, "announce stream ended") } +/// A timestamp in microseconds. +private func micros(_ value: UInt64) -> Timestamp { + Timestamp(value: value, scale: 1_000_000) +} + +/// Assert `body` throws `MoqError.TimeOverflow`. +private func assertTimeOverflow( + _ body: @autoclosure () throws -> T, file: StaticString = #filePath, line: UInt = #line +) { + XCTAssertThrowsError(try body(), file: file, line: line) { error in + guard case MoqError.TimeOverflow = error else { + return XCTFail("expected TimeOverflow, got \(error)", file: file, line: line) + } + } +} + final class SmokeTests: XCTestCase { func testDefaultSubscriptionSkipsSupersededGroupsAtOnce() { XCTAssertEqual(Subscription.default.maxDelay, 0) @@ -50,7 +66,7 @@ final class SmokeTests: XCTestCase { let track = try broadcast.publishTrack(name: "backlog", info: TrackInfo(timescale: 1_000_000)) for ms: UInt64 in 0..<3 { let group = try track.appendGroup() - try group.writeFrame(Data("x".utf8), timestampUs: ms * 1_000) + try group.writeFrame(Data("x".utf8), timestamp: micros(ms * 1_000)) try group.finish() } let consumer = try track.consume( @@ -365,7 +381,7 @@ final class SmokeTests: XCTestCase { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "events", info: TrackInfo(timescale: 1_000_000)) let group = try track.appendGroup() - try group.writeFrame(Data("cached".utf8), timestampUs: 0) + try group.writeFrame(Data("cached".utf8), timestamp: micros(0)) try group.finish() let consumer = try broadcast.consume() @@ -395,16 +411,16 @@ final class SmokeTests: XCTestCase { track: try await broadcast.consume().subscribeTrack(name: "status")) for viewers in 1...4 { - try producer.update(Status(state: "live", viewers: viewers), timestampUs: UInt64(viewers) * 1000) + try producer.update(Status(state: "live", viewers: viewers), timestamp: micros(UInt64(viewers) * 1000)) } // `next` yields every state in order; `latest` skips the buffered third. let first = try await consumer.next() - XCTAssertEqual(first, Json.Timed(value: Status(state: "live", viewers: 1), timestampUs: 1000)) + XCTAssertEqual(first, Json.Timed(value: Status(state: "live", viewers: 1), timestamp: micros(1000))) let second = try await consumer.next() - XCTAssertEqual(second, Json.Timed(value: Status(state: "live", viewers: 2), timestampUs: 2000)) + XCTAssertEqual(second, Json.Timed(value: Status(state: "live", viewers: 2), timestamp: micros(2000))) let latest = try await consumer.latest() - XCTAssertEqual(latest, Json.Timed(value: Status(state: "live", viewers: 4), timestampUs: 4000)) + XCTAssertEqual(latest, Json.Timed(value: Status(state: "live", viewers: 4), timestamp: micros(4000))) consumer.cancel() try producer.finish() @@ -425,7 +441,7 @@ final class SmokeTests: XCTestCase { for n in 0..<3 { try producer.append(Event(n: n)) let record = try await consumer.next() - XCTAssertEqual(record, Json.Timed(value: Event(n: n), timestampUs: nil)) + XCTAssertEqual(record, Json.Timed(value: Event(n: n), timestamp: nil)) } consumer.cancel() @@ -445,23 +461,24 @@ final class SmokeTests: XCTestCase { track: try await broadcast.consume().subscribeTrack(name: "log")) for n in 0..<3 { - try producer.push(Event(n: n), timestampUs: UInt64(n) * 1000) + try producer.push(Event(n: n), timestamp: micros(UInt64(n) * 1000)) } - try producer.pop(2, timestampUs: 3000) + try producer.pop(2, timestamp: micros(3000)) for n in 0..<3 { let event = try await consumer.next() XCTAssertEqual( - event, Json.Timed(value: .push(index: UInt64(n), value: Event(n: n)), timestampUs: UInt64(n) * 1000)) + event, + Json.Timed(value: .push(index: UInt64(n), value: Event(n: n)), timestamp: micros(UInt64(n) * 1000))) } let pop = try await consumer.next() - XCTAssertEqual(pop, Json.Timed(value: .pop(0..<2), timestampUs: 3000)) + XCTAssertEqual(pop, Json.Timed(value: .pop(0..<2), timestamp: micros(3000))) // The cut's new group restates record 2, which this reader already has. try producer.cut() - try producer.push(Event(n: 3), timestampUs: 4000) + try producer.push(Event(n: 3), timestamp: micros(4000)) let pushed = try await consumer.next() - XCTAssertEqual(pushed, Json.Timed(value: .push(index: 3, value: Event(n: 3)), timestampUs: 4000)) + XCTAssertEqual(pushed, Json.Timed(value: .push(index: 3, value: Event(n: 3)), timestamp: micros(4000))) try producer.finish() let end = try await consumer.next() @@ -505,7 +522,7 @@ final class SmokeTests: XCTestCase { let received = try await consumer.readFrame() let frame = try XCTUnwrap(received) XCTAssertEqual(frame.payload, Data("payload".utf8)) - XCTAssertNil(frame.timestampUs) + XCTAssertNil(frame.timestamp) XCTAssertNil(consumer.info().timescale) try track.finish() try broadcast.close() @@ -517,26 +534,85 @@ final class SmokeTests: XCTestCase { let consumer = try track.consume() let payload = Data("ready".utf8) - try track.writeFrame(payload, timestampUs: 12_345) + try track.writeFrame(payload, timestamp: micros(12_345)) let frame = try await consumer.readFrame() XCTAssertEqual(frame?.payload, payload) - XCTAssertEqual(frame?.timestampUs, 12_345) + XCTAssertEqual(frame?.timestamp, micros(12_345)) let group = try track.appendGroup() let groupConsumer = try group.consume() let groupPayload = Data("group".utf8) - try group.writeFrame(groupPayload, timestampUs: 23_456) + try group.writeFrame(groupPayload, timestamp: micros(23_456)) try group.finish() let groupFrame = try await groupConsumer.readFrame() XCTAssertEqual(groupFrame?.payload, groupPayload) - XCTAssertEqual(groupFrame?.timestampUs, 23_456) + XCTAssertEqual(groupFrame?.timestamp, micros(23_456)) + + try track.finish() + try broadcast.close() + } + + func testTimestampsAreExact() async throws { + let broadcast = try BroadcastProducer() + let track = try broadcast.publishTrack(name: "video", info: TrackInfo(timescale: 90_000)) + let consumer = try track.consume() + + // A present zero stays present, and one 90 kHz tick reads back as itself rather than + // the 11 µs it floors to. + for value: UInt64 in [0, 1] { + let timestamp = Timestamp(value: value, scale: 90_000) + try track.writeFrame(Data("frame".utf8), timestamp: timestamp) + let frame = try await consumer.readFrame() + XCTAssertEqual(frame?.timestamp, timestamp) + } + + for invalid in [ + Timestamp(value: 0, scale: 0), + Timestamp(value: 0, scale: 1 << 62), + Timestamp(value: 1 << 61, scale: 90_000), + ] { + assertTimeOverflow(try track.writeFrame(Data("frame".utf8), timestamp: invalid)) + } try track.finish() try broadcast.close() } + @available(macOS 13, iOS 16, *) + func testTimestampDurations() throws { + // Exact at the finest power-of-ten scale whose value fits. + let atto: UInt64 = 1_000_000_000_000_000_000 + XCTAssertEqual(try Timestamp(.zero), Timestamp(value: 0, scale: atto)) + XCTAssertEqual(try Timestamp(.milliseconds(20)), Timestamp(value: atto / 50, scale: atto)) + XCTAssertEqual(try Timestamp(.seconds(3_600)), Timestamp(value: 3_600 * (atto / 10_000), scale: atto / 10_000)) + XCTAssertEqual(try Timestamp(.seconds((1 << 61) - 1)), Timestamp(value: (1 << 61) - 1, scale: 1)) + assertTimeOverflow(try Timestamp(.seconds(1 << 61))) + assertTimeOverflow(try Timestamp(.seconds(-1))) + // Three seconds of attoseconds passes 2^61, and the attosecond doesn't survive a coarser scale. + assertTimeOverflow(try Timestamp(.seconds(3) + Duration(secondsComponent: 0, attosecondsComponent: 1))) + + // Back down to a whole attosecond: a 90 kHz tick is 11_111_111_111_111.1 as, 2/3 s ends in + // ...6.6 as, and half an attosecond is 0. + let tick = Duration(secondsComponent: 0, attosecondsComponent: 11_111_111_111_111) + XCTAssertEqual(try Timestamp(value: 1, scale: 90_000).duration, tick) + let twoThirds = Duration(secondsComponent: 0, attosecondsComponent: 666_666_666_666_666_666) + XCTAssertEqual(try Timestamp(value: 2, scale: 3).duration, twoThirds) + XCTAssertEqual(try Timestamp(value: 1, scale: 2 * atto).duration, .zero) + XCTAssertEqual(try micros(1_500_000).duration, .milliseconds(1_500)) + XCTAssertEqual(try Timestamp(.seconds(3_600)).duration, .seconds(3_600)) + + // A record outside what a write accepts is refused rather than converted. + for invalid in [ + Timestamp(value: 0, scale: 0), + Timestamp(value: 0, scale: 1 << 62), + Timestamp(value: 1 << 61, scale: 90_000), + ] { + assertTimeOverflow(try invalid.duration) + } + } + func testReadFrameSkipsEmptyThenPopulatedGroups() async throws { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "status", info: TrackInfo(timescale: 1_000_000)) @@ -544,11 +620,11 @@ final class SmokeTests: XCTestCase { try track.appendGroup().finish() try track.appendGroup().finish() - try track.writeFrame(Data("populated".utf8), timestampUs: 2_000) + try track.writeFrame(Data("populated".utf8), timestamp: micros(2_000)) let frame = try await consumer.readFrame() XCTAssertEqual(frame?.payload, Data("populated".utf8)) - XCTAssertEqual(frame?.timestampUs, 2_000) + XCTAssertEqual(frame?.timestamp, micros(2_000)) try track.finish() try broadcast.close() @@ -582,7 +658,7 @@ final class SmokeTests: XCTestCase { track: "fine" ) // 2.5 ms of silence at 48 kHz mono f32: exactly one encoded frame. - try fine.write(AudioFrame(timestampUs: 0, data: Data(count: 120 * 4))) + try fine.write(AudioFrame(timestamp: micros(0), data: Data(count: 120 * 4))) try fine.finish() XCTAssertThrowsError( @@ -634,7 +710,7 @@ final class SmokeTests: XCTestCase { // Two 20 ms Opus frames of silence at 48 kHz mono. for i in 0..<2 { - try audio.write(AudioFrame(timestampUs: UInt64(i) * 20_000, data: Data(count: 960 * 4))) + try audio.write(AudioFrame(timestamp: micros(UInt64(i) * 20_000), data: Data(count: 960 * 4))) } let fixedFrame = try await fixed.next() XCTAssertNotNil(fixedFrame) @@ -669,7 +745,7 @@ final class SmokeTests: XCTestCase { let rgba = Data(repeating: 0x80, count: 320 * 240 * 4) try video.cut() for i in 0..<10 { - try video.write(VideoFrame(timestampUs: UInt64(i) * 33_333, data: rgba)) + try video.write(VideoFrame(timestamp: micros(UInt64(i) * 33_333), data: rgba)) } let consumer = try await origin.consume().request(path: "video-decode-frame") @@ -683,7 +759,7 @@ final class SmokeTests: XCTestCase { // Keep the encoder fed so the decoder sees frames after it joined. for i in 10..<40 { - try video.write(VideoFrame(timestampUs: UInt64(i) * 33_333, data: rgba)) + try video.write(VideoFrame(timestamp: micros(UInt64(i) * 33_333), data: rgba)) } let next = try await decoder.next() @@ -706,7 +782,7 @@ final class SmokeTests: XCTestCase { func testEncodeAudioWithOpusObject() throws { // The config retains the codec, so releasing either first must still encode. let input = AudioEncoderInput(format: .f32, sampleRate: 48_000, channels: 1) - let silence = AudioFrame(timestampUs: 0, data: Data(count: 960 * 4)) + let silence = AudioFrame(timestamp: micros(0), data: Data(count: 960 * 4)) // Release the codec before encoding: `output` retains it. do { diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index cabba3f28d4..cc4ff43f0da 100644 --- a/test/interop/clients/c/subscribe.c +++ b/test/interop/clients/c/subscribe.c @@ -171,7 +171,10 @@ static void on_audio(void *ud, int32_t id) { moq_audio_frame f = read.frame; if (status == 0 && read.kind == MOQ_DECODE_READ_FRAME && a->samples < a->want) { uint64_t samples = f.data_size / a->frame_bytes; - fprintf(a->log, "%llu %llu\n", (unsigned long long)f.timestamp_us, (unsigned long long)samples); + // tone.py reads whole microseconds; splitting off the seconds keeps the product in range. + moq_timestamp ts = f.timestamp; + unsigned long long us = ts.value / ts.scale * 1000000 + ts.value % ts.scale * 1000000 / ts.scale; + fprintf(a->log, "%llu %llu\n", us, (unsigned long long)samples); fwrite(f.data, 1, f.data_size, a->pcm); a->samples += samples; if (a->samples >= a->want) { diff --git a/test/interop/clients/cpp/main.cpp b/test/interop/clients/cpp/main.cpp index 4771c32061d..37a3fda1adf 100644 --- a/test/interop/clients/cpp/main.cpp +++ b/test/interop/clients/cpp/main.cpp @@ -168,8 +168,7 @@ void publish_tone( ) { const auto started = Clock::now(); std::vector data(AUDIO_BATCH_SAMPLES * tones.size() * sizeof(float)); - uint64_t timestamp_us = 0; - size_t phase = 0; + uint64_t phase = 0; while (!stop.load()) { for (size_t i = 0; i < AUDIO_BATCH_SAMPLES; i++) { for (size_t c = 0; c < tones.size(); c++) { @@ -180,11 +179,10 @@ void publish_tone( std::memcpy(&data[(i * tones.size() + c) * sizeof(float)], &sample, sizeof(float)); } } - ok(audio->write({timestamp_us, data}), "tone write"); + ok(audio->write({{phase, AUDIO_RATE}, data}), "tone write"); phase += AUDIO_BATCH_SAMPLES; - timestamp_us += AUDIO_BATCH_US; // Pace against the start, so encoding cost doesn't accumulate as drift. - std::this_thread::sleep_until(started + std::chrono::microseconds(timestamp_us)); + std::this_thread::sleep_until(started + std::chrono::microseconds(phase * 1'000'000 / AUDIO_RATE)); } } @@ -319,7 +317,9 @@ void decode_audio( const auto *frame = &variant->frame; const size_t samples = frame->data.size() / frame_bytes; - log << frame->timestamp_us << " " << samples << "\n"; + // tone.py reads whole microseconds; splitting off the seconds keeps the product in range. + const auto &ts = frame->timestamp; + log << ts.value / ts.scale * 1'000'000 + ts.value % ts.scale * 1'000'000 / ts.scale << " " << samples << "\n"; pcm.write(reinterpret_cast(frame->data.data()), static_cast(frame->data.size())); decoded += samples; } diff --git a/test/interop/clients/go/main.go b/test/interop/clients/go/main.go index 8082754527c..8ab4f683d5d 100644 --- a/test/interop/clients/go/main.go +++ b/test/interop/clients/go/main.go @@ -73,7 +73,6 @@ func publishTone(ctx context.Context, audio *moqaudio.Producer, tones []float64) defer ticker.Stop() data := make([]byte, audioBatchSamples*len(tones)*4) - timestampUs := uint64(0) phase := 0 for { select { @@ -87,12 +86,12 @@ func publishTone(ctx context.Context, audio *moqaudio.Producer, tones []float64) binary.LittleEndian.PutUint32(data[(i*len(tones)+c)*4:], math.Float32bits(float32(sample))) } } - if err := audio.Write(moqaudio.Frame{Timestamp: time.Duration(timestampUs) * time.Microsecond, Data: data}); err != nil { + // Stamped on the sample clock, so every batch time is exact. + if err := audio.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Value: uint64(phase), Scale: audioRate}, Data: data}); err != nil { fmt.Fprintf(os.Stderr, "tone: %v\n", err) return } phase += audioBatchSamples - timestampUs += audioBatchUs } } @@ -504,7 +503,7 @@ func decodeAudio(ctx context.Context, consumer *moq.BroadcastConsumer, id string } samples := len(frame.Data) / frameBytes - fmt.Fprintf(log, "%d %d\n", frame.Timestamp.Microseconds(), samples) + fmt.Fprintf(log, "%d %d\n", moq.TimestampToDuration(frame.Timestamp).Microseconds(), samples) if _, err := pcm.Write(frame.Data); err != nil { return err } diff --git a/test/interop/clients/python/interop.py b/test/interop/clients/python/interop.py index 6e663509991..cf0a899a87f 100644 --- a/test/interop/clients/python/interop.py +++ b/test/interop/clients/python/interop.py @@ -65,7 +65,7 @@ async def _publish_tone(audio: moq.audio.Producer, tones: list[int]) -> None: ] audio.write( moq.audio.Frame( - timestamp=timedelta(microseconds=timestamp_us), data=struct.pack(f"<{len(samples)}f", *samples) + timestamp=moq.Timestamp(timestamp_us, 1_000_000), data=struct.pack(f"<{len(samples)}f", *samples) ) ) phase += AUDIO_BATCH_SAMPLES @@ -275,7 +275,7 @@ async def _decode_audio( if isinstance(frame, moq.audio.End): raise RuntimeError("audio track ended early") samples = len(frame.data) // frame_bytes - log.write(f"{frame.timestamp // timedelta(microseconds=1)} {samples}\n") + log.write(f"{frame.timestamp.to_timedelta() // timedelta(microseconds=1)} {samples}\n") pcm.write(frame.data) decoded += samples if decoded * 1000 >= audio_ms * audio.sample_rate: