From 7165794e0d8a4427625a5ca61eef53286e4f276d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 11:31:38 -0800 Subject: [PATCH 01/11] chore(quest): claim quest/m1/video-rate/obs.md Quest-Claim: 0a51207ee6fa5315 From ab83f278ab2da14a8d07a74086ad28f25b604c91 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 11:45:49 -0800 Subject: [PATCH 02/11] feat(obs): dock profiles run capped VBR where the encoder honors a peak x264 runs VBR (CRF under a VBV max rate) and NVENC runs CQVBR with max_bitrate, at the profile's bitrate as the peak; other encoders stay CBR. The catalog bitrate carries the peak, and dynamic bitrate retunes it (NVENC's under max_bitrate). Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-dock.cpp | 14 +++-- cpp/obs/src/moq-encoder-rate.h | 64 +++++++++++++++++++ cpp/obs/src/moq-output.cpp | 59 +++++++++++++----- cpp/obs/src/moq-output.h | 2 + cpp/obs/test/moq-encoder-rate-test.cpp | 81 ++++++++++++++++++++++++ cpp/obs/test/moq-output-test.cpp | 85 +++++++++++++++++++++----- doc/bin/obs.md | 20 ++++-- quest/m1/video-rate/obs.md | 41 ++++++++----- sh/obs/unit.sh | 2 +- 9 files changed, 310 insertions(+), 58 deletions(-) create mode 100644 cpp/obs/src/moq-encoder-rate.h create mode 100644 cpp/obs/test/moq-encoder-rate-test.cpp diff --git a/cpp/obs/src/moq-dock.cpp b/cpp/obs/src/moq-dock.cpp index e95e372f31e..894b57f6f99 100644 --- a/cpp/obs/src/moq-dock.cpp +++ b/cpp/obs/src/moq-dock.cpp @@ -6,6 +6,7 @@ #include "moq-dial.h" #include "moq-spark-data.h" #include "moq-encoder-latency.h" +#include "moq-encoder-rate.h" #include "moq-quality-defaults.h" #include "moq-settings.h" #include "logger.h" @@ -967,8 +968,7 @@ bool MoQDock::CreateCustomEncoders() OBSDataAutoRelease videoSettings = obs_data_create(); OBSDataAutoRelease audioSettings = obs_data_create(); - obs_data_set_int(videoSettings, "bitrate", videoBitrate); - obs_data_set_string(videoSettings, "rate_control", "CBR"); + const bool capped = ApplyEncoderRate(videoId.toStdString(), videoSettings, videoBitrate); obs_data_set_bool(videoSettings, "repeat_headers", true); obs_data_set_int(audioSettings, "bitrate", audioBitrate); @@ -995,8 +995,9 @@ bool MoQDock::CreateCustomEncoders() obs_encoder_set_video(videoEncoder, obs_get_video()); obs_encoder_set_audio(audioEncoder, obs_get_audio()); - LOG_INFO("Using dock custom encoders: %s / %s (profile %s, %d kbps)", videoId.toUtf8().constData(), - audioId.toUtf8().constData(), high ? "quality" : "performance", videoBitrate); + LOG_INFO("Using dock custom encoders: %s / %s (profile %s, %s %d kbps)", videoId.toUtf8().constData(), + audioId.toUtf8().constData(), high ? "quality" : "performance", capped ? "capped VBR, peak" : "CBR", + videoBitrate); QString profileLabel = high ? QStringLiteral("Quality") : QStringLiteral("Performance"); if (profile == "auto") @@ -1004,10 +1005,11 @@ bool MoQDock::CreateCustomEncoders() const char *videoDisplay = obs_encoder_get_display_name(videoId.toUtf8().constData()); const char *audioDisplay = obs_encoder_get_display_name(audioId.toUtf8().constData()); const QString pathLabel = preferHw ? QStringLiteral("Hardware") : QStringLiteral("Software"); - publishSummary = QString("Preset %1 · %2\nVideo %3 · %4 · %5 kbps\nAudio %6 · %7 · %8 kbps") + publishSummary = QString("Preset %1 · %2\nVideo %3 · %4 · %5 %6 kbps\nAudio %7 · %8 · %9 kbps") .arg(profileLabel, pathLabel, codec.isEmpty() ? QStringLiteral("video") : codec.toUpper(), - videoDisplay && *videoDisplay ? QString::fromUtf8(videoDisplay) : videoId) + videoDisplay && *videoDisplay ? QString::fromUtf8(videoDisplay) : videoId, + capped ? QStringLiteral("up to") : QStringLiteral("CBR")) .arg(videoBitrate) .arg(audioChoice.isEmpty() ? QStringLiteral("audio") : audioChoice.toUpper(), audioDisplay && *audioDisplay ? QString::fromUtf8(audioDisplay) : audioId) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h new file mode 100644 index 00000000000..cd20715e717 --- /dev/null +++ b/cpp/obs/src/moq-encoder-rate.h @@ -0,0 +1,64 @@ +// SPDX-License-Identifier: GPL-2.0-or-later +#pragma once + +#include +#include +#include + +// The setting that holds the hard peak an encoder honors under `rate_control`, or null +// when it has none (CQP, CRF, ICQ, or a mode that only averages). The peak is what +// reservations, the catalog, and dynamic bitrate price a rendition at. +inline const char *EncoderPeakKey(const std::string &id, std::string rate_control) +{ + for (char &c : rate_control) + c = static_cast(std::toupper(static_cast(c))); + // CBR holds the encoder at its bitrate, so that is also its peak. + if (rate_control == "CBR") + return "bitrate"; + // x264's VBR is constant quality (CRF) under a VBV whose max rate is the bitrate. + if (id == "obs_x264") + return rate_control == "VBR" ? "bitrate" : nullptr; + // NVENC's VBR averages at "bitrate" but never exceeds "max_bitrate"; CQVBR is + // constant quality under that same max, and ignores "bitrate". + if (id.rfind("obs_nvenc_", 0) == 0) + return rate_control == "VBR" || rate_control == "CQVBR" ? "max_bitrate" : nullptr; + return nullptr; +} + +// An encoder's hard peak in kbps and the setting that holds it. +struct MoQPeak { + const char *key = nullptr; + long long kbps = 0; +}; + +// The peak these encoder settings configure, with a null key when they configure none. +inline MoQPeak EncoderPeak(const std::string &id, obs_data_t *settings) +{ + const char *key = EncoderPeakKey(id, obs_data_get_string(settings, "rate_control")); + if (!key) + return {}; + const long long kbps = obs_data_get_int(settings, key); + return kbps > 0 ? MoQPeak{key, kbps} : MoQPeak{}; +} + +// Configures `settings` to run `id` at constant quality under a peak of `cap_kbps`, where +// the encoder honors one, and at CBR at that rate where it does not, so it never +// exceeds the rate a viewer priced it at. Returns whether the quality mode took. +// The quality level is the encoder's own default. +inline bool ApplyEncoderRate(const std::string &id, obs_data_t *settings, long long cap_kbps) +{ + obs_data_set_int(settings, "bitrate", cap_kbps); + if (id == "obs_x264") { + obs_data_set_string(settings, "rate_control", "VBR"); + return true; + } + if (id.rfind("obs_nvenc_", 0) == 0) { + obs_data_set_string(settings, "rate_control", "CQVBR"); + obs_data_set_int(settings, "max_bitrate", cap_kbps); + return true; + } + // Quick Sync's ICQ and AMF's QVBR carry no peak, VA-API's QVBR depends on the driver, + // and VideoToolbox's quality mode needs a Mac to check. + obs_data_set_string(settings, "rate_control", "CBR"); + return false; +} diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 399b8774c1c..cf8c9e32853 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -2,6 +2,7 @@ #include #include "moq-output.h" +#include "moq-encoder-rate.h" #include "moq-error.h" #include "moq-implementation.h" #include "moq-settings.h" @@ -72,14 +73,32 @@ const moq::Error *PhaseFailure(const moq::ConnectionPhase &phase) phase.get_variant()); } -// Retune `encoder` to `bitrate_bps`, the way OBS's own RTMP dynamic bitrate does. -void SetBitrate(obs_encoder_t *encoder, uint64_t bitrate_bps) +// Retune `encoder` to `bitrate_bps` in its `key` setting, the way OBS's own RTMP dynamic +// bitrate does. The key is where the encoder holds its peak: "bitrate" for most, but +// "max_bitrate" for NVENC's constant quality. +void SetBitrate(obs_encoder_t *encoder, const char *key, uint64_t bitrate_bps) { OBSDataAutoRelease settings = obs_data_create(); - obs_data_set_int(settings, "bitrate", (long long)(bitrate_bps / 1000)); + obs_data_set_int(settings, key, (long long)(bitrate_bps / 1000)); obs_encoder_update(encoder, settings); } +// The kbps this encoder is priced at: its hard peak when it has one, else its bitrate +// setting, which a quality target (CQP, CRF) only reserves. +int EncoderCapKbps(const MoQPeak &peak, obs_data_t *settings) +{ + if (peak.key) + return (int)peak.kbps; + return settings ? (int)obs_data_get_int(settings, "bitrate") : 0; +} + +// The hard peak `encoder`'s settings configure, if any. +MoQPeak PeakOf(obs_encoder_t *encoder, obs_data_t *settings) +{ + const char *id = obs_encoder_get_id(encoder); + return settings && id ? EncoderPeak(id, settings) : MoQPeak{}; +} + // Whether `rate_control` lets the "bitrate" setting drive the encoder's output. // Encoders without the setting are bitrate-driven by construction. bool BitrateDriven(const std::string &rate_control) @@ -392,7 +411,12 @@ void MoQOutput::Reset() // Following the grant rewrote the encoder's bitrate, which the next Start() // reads back as the configured rate. Restored after media_mutex is released: // an idle encoder applies the update inline. - std::vector> restore; + struct Restore { + OBSEncoder encoder; + const char *key; + uint64_t bitrate_bps; + }; + std::vector restore; std::unique_lock lock(media_mutex); for (auto &[encoder, track] : video_tracks) { @@ -400,7 +424,7 @@ void MoQOutput::Reset() track.producer->finish(); if (track.rate && track.applied_bps != track.bitrate_bps) { if (OBSEncoder strong = OBSGetStrongRef(track.encoder)) - restore.emplace_back(std::move(strong), track.bitrate_bps); + restore.push_back({std::move(strong), track.rate_key, track.bitrate_bps}); } } video_tracks.clear(); @@ -436,8 +460,8 @@ void MoQOutput::Reset() lock.unlock(); - for (auto &[encoder, bitrate] : restore) - SetBitrate(encoder, bitrate); + for (auto &r : restore) + SetBitrate(r.encoder, r.key, r.bitrate_bps); } std::string MoQOutput::GetInstance() @@ -738,7 +762,7 @@ void MoQOutput::VideoData(struct encoder_packet *packet) void MoQOutput::Retarget(obs_encoder_t *encoder, Track &track, const moq::RateTarget &target) { if (const auto *enabled = std::get_if(&target.get_variant())) { - SetBitrate(encoder, enabled->bitrate_bps); + SetBitrate(encoder, track.rate_key, enabled->bitrate_bps); track.applied_bps = enabled->bitrate_bps; track.enabled = true; return; @@ -788,7 +812,8 @@ void MoQOutput::VideoInit(obs_encoder_t *encoder) OBSDataAutoRelease settings = obs_encoder_get_settings(encoder); const auto video_width = obs_encoder_get_width(encoder); const auto video_height = obs_encoder_get_height(encoder); - const int video_bitrate_kbps = settings ? (int)obs_data_get_int(settings, "bitrate") : 0; + const MoQPeak peak = PeakOf(encoder, settings); + const int video_bitrate_kbps = EncoderCapKbps(peak, settings); uint8_t *extra_data = nullptr; size_t extra_size = 0; @@ -820,13 +845,14 @@ void MoQOutput::VideoInit(obs_encoder_t *encoder) config.data.assign(extra_data, extra_data + extra_size); // Seed catalog fields a downstream moq-transcode needs before measured rates - // arrive: coded size (also from SPS once parsed) and configured CBR bitrate so - // same-height ladder rungs can undercut the mezzanine. + // arrive: coded size (also from SPS once parsed) and the encoder's hard peak, which + // CBR and capped VBR both configure, so same-height ladder rungs can undercut the + // mezzanine. The catalog prices a rendition at that peak, never its measured rate. moq::VideoHint hint{}; if (video_width > 0 && video_height > 0) hint.coded = moq::Dimensions{video_width, video_height}; const std::string rate_control = settings ? obs_data_get_string(settings, "rate_control") : ""; - if (video_bitrate_kbps > 0 && (rate_control == "CBR" || rate_control == "cbr")) + if (peak.key) hint.bitrate = (uint64_t)video_bitrate_kbps * 1000ULL; hint.optimize_for_latency = true; config.hint = hint; @@ -847,7 +873,7 @@ void MoQOutput::VideoInit(obs_encoder_t *encoder) kbps = (int)(known->second.bitrate_bps / 1000); } else { OBSDataAutoRelease other_settings = obs_encoder_get_settings(other); - kbps = other_settings ? (int)obs_data_get_int(other_settings, "bitrate") : 0; + kbps = EncoderCapKbps(PeakOf(other, other_settings), other_settings); } if (kbps > lower_kbps && kbps < video_bitrate_kbps) { lower = other; @@ -887,10 +913,11 @@ void MoQOutput::VideoInit(obs_encoder_t *encoder) entry.producer = *track; if (video_bitrate_kbps > 0) { entry.bitrate_bps = (uint64_t)video_bitrate_kbps * 1000ULL; - // Following needs an encoder that retunes live and a rate control the - // bitrate drives; a quality target (CQP, CRF) only reserves. + // Following needs an encoder that retunes live and either holds a peak or has a + // rate control the bitrate drives; a quality target (CQP, CRF) only reserves. const bool dynamic = obs_encoder_get_caps(encoder) & OBS_ENCODER_CAP_DYN_BITRATE; - if (dynamic && BitrateDriven(rate_control)) { + if (dynamic && (peak.key || BitrateDriven(rate_control))) { + entry.rate_key = peak.key ? peak.key : "bitrate"; entry.rate = moq::RateControl::init(moq::RatePolicy{entry.bitrate_bps, lower_bps}); entry.applied_bps = entry.bitrate_bps; entry.encoder = OBSGetWeakRef(encoder); diff --git a/cpp/obs/src/moq-output.h b/cpp/obs/src/moq-output.h index c3d49eea326..4d3e0c60988 100644 --- a/cpp/obs/src/moq-output.h +++ b/cpp/obs/src/moq-output.h @@ -130,6 +130,8 @@ class MoQOutput { // weak ref so Reset() can hand the configured bitrate back. std::shared_ptr rate; OBSWeakEncoder encoder; + // The encoder setting that holds its peak, which following the grant retunes. + const char *rate_key = "bitrate"; // The bitrate the encoder was last told, which Reset() restores when it moved. uint64_t applied_bps = 0; // Whether the last target enabled this rendition. diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp new file mode 100644 index 00000000000..e97ae03637f --- /dev/null +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -0,0 +1,81 @@ +// SPDX-License-Identifier: GPL-2.0-or-later +#include "moq-encoder-rate.h" + +#include +#include +#include +#include + +struct obs_data { + std::map> values; +}; + +const char *obs_data_get_string(obs_data_t *data, const char *key) +{ + auto entry = data->values.find(key); + return entry == data->values.end() ? "" : std::get(entry->second).c_str(); +} +long long obs_data_get_int(obs_data_t *data, const char *key) +{ + auto entry = data->values.find(key); + return entry == data->values.end() ? 0 : std::get(entry->second); +} +void obs_data_set_string(obs_data_t *data, const char *key, const char *value) +{ + data->values[key] = std::string(value); +} +void obs_data_set_int(obs_data_t *data, const char *key, long long value) +{ + data->values[key] = value; +} + +static std::string rate_control(obs_data_t &settings) +{ + return obs_data_get_string(&settings, "rate_control"); +} + +int main() +{ + // x264 and NVENC take constant quality under the cap. + obs_data_t x264; + assert(ApplyEncoderRate("obs_x264", &x264, 8000)); + assert(rate_control(x264) == "VBR" && obs_data_get_int(&x264, "bitrate") == 8000); + assert(EncoderPeak("obs_x264", &x264).kbps == 8000); + + for (const char *id : {"obs_nvenc_h264_tex", "obs_nvenc_hevc_soft", "obs_nvenc_av1_tex"}) { + obs_data_t nvenc; + assert(ApplyEncoderRate(id, &nvenc, 2500)); + assert(rate_control(nvenc) == "CQVBR" && obs_data_get_int(&nvenc, "max_bitrate") == 2500); + // The peak is max_bitrate: CQVBR ignores the bitrate. + const MoQPeak peak = EncoderPeak(id, &nvenc); + assert(std::string(peak.key) == "max_bitrate" && peak.kbps == 2500); + } + + // An encoder whose quality mode carries no hard peak stays at CBR, which is its peak. + for (const char *id : {"obs_qsv11_v2", "obs_qsv11_av1", "h264_texture_amf", "ffmpeg_vaapi_tex", + "com.apple.videotoolbox.videoencoder.ave.avc", "ffmpeg_nvenc", "unknown"}) { + obs_data_t other; + assert(!ApplyEncoderRate(id, &other, 8000)); + assert(rate_control(other) == "CBR" && obs_data_get_int(&other, "bitrate") == 8000); + const MoQPeak peak = EncoderPeak(id, &other); + assert(std::string(peak.key) == "bitrate" && peak.kbps == 8000); + } + + // What a user configured decides the peak, whatever the encoder. + assert(std::string(EncoderPeakKey("obs_x264", "cbr")) == "bitrate"); + assert(std::string(EncoderPeakKey("obs_nvenc_h264_tex", "vbr")) == "max_bitrate"); + assert(std::string(EncoderPeakKey("obs_nvenc_h264_tex", "CBR")) == "bitrate"); + for (const char *mode : {"CRF", "ABR", "CQP", "ICQ", "QVBR", "lossless", ""}) { + assert(!EncoderPeakKey("obs_x264", mode) && !EncoderPeakKey("obs_nvenc_h264_tex", mode)); + } + assert(!EncoderPeakKey("obs_qsv11_v2", "VBR")); + + // A peak of 0 is none: NVENC reads it as the driver's own limit. + obs_data_t unbounded; + obs_data_set_string(&unbounded, "rate_control", "CQVBR"); + obs_data_set_int(&unbounded, "max_bitrate", 0); + assert(!EncoderPeak("obs_nvenc_h264_tex", &unbounded).key); + + printf("encoder rate: ok\n"); + return 0; +} diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index b883589d693..ec9d1ba06d1 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -21,6 +21,7 @@ #include #include #include +#include #include #include @@ -55,10 +56,12 @@ std::atomic g_destroyed{false}; std::string g_url; std::string g_rate_control = "CBR"; +std::string g_encoder_id = "obs_x264"; uint32_t g_encoder_caps = OBS_ENCODER_CAP_DYN_BITRATE; -// Every obs_encoder_update, as the encoder and the bitrate it was told in kbps. +// Every obs_encoder_update, as the encoder, the setting, and the kbps it was told. +using Update = std::tuple; std::mutex g_updates_mutex; -std::vector> g_updates; +std::vector g_updates; std::atomic g_settings_ok{true}; // A reason Configure reports itself, for a setting the config cannot express. std::string g_settings_error; @@ -175,6 +178,11 @@ bool obs_encoder_get_extra_data(const obs_encoder_t *encoder, uint8_t **data, si return true; } +const char *obs_encoder_get_id(const obs_encoder_t *) +{ + return g_encoder_id.c_str(); +} + const char *obs_encoder_get_codec(const obs_encoder_t *encoder) { return encoder == AUDIO_ENCODER ? "opus" : "h264"; @@ -210,8 +218,9 @@ long long obs_data_get_int(obs_data_t *settings, const char *) return settings == reinterpret_cast(MID_ENCODER) ? 4000 : 8000; } -// The settings a retune builds carry only the bitrate, so the stub is that bitrate. +// The settings a retune builds carry only the one rate, so the stub is that setting. struct obs_data { + std::string key; long long bitrate = 0; }; @@ -220,8 +229,9 @@ obs_data_t *obs_data_create() return new obs_data; } -void obs_data_set_int(obs_data_t *data, const char *, long long value) +void obs_data_set_int(obs_data_t *data, const char *key, long long value) { + data->key = key; data->bitrate = value; } @@ -233,7 +243,7 @@ uint32_t obs_encoder_get_caps(const obs_encoder_t *) void obs_encoder_update(obs_encoder_t *encoder, obs_data_t *settings) { std::lock_guard lock(g_updates_mutex); - g_updates.emplace_back(encoder, settings->bitrate); + g_updates.emplace_back(encoder, settings->key, settings->bitrate); delete settings; } @@ -318,6 +328,7 @@ void reset(std::string url) g_settings_ok = true; g_settings_error.clear(); g_rate_control = "CBR"; + g_encoder_id = "obs_x264"; g_encoder_caps = OBS_ENCODER_CAP_DYN_BITRATE; g_ladder = false; g_mid = false; @@ -504,7 +515,7 @@ struct MoQOutputStatsTest { } }; -std::vector> updates() +std::vector updates() { std::lock_guard lock(g_updates_mutex); return g_updates; @@ -578,12 +589,23 @@ int main() printf("retired stats never replace the accepted sample: ok\n"); // Publishes over a real session: connects, reports itself live, carries - // stats, and lands video and audio renditions in the relay's catalog. Only CBR - // publishes the configured bitrate as a hint. - for (const char *mode : {"CBR", "VBR"}) { + // stats, and lands video and audio renditions in the relay's catalog. The catalog + // prices a video rendition at the hard peak its encoder holds: the bitrate under + // CBR, and the cap under x264's and NVENC's capped VBR. An encoder that only + // averages, or targets a quality, advertises none. + struct HintCase { + const char *id; + const char *mode; + bool hint; + }; + for (const auto &c : + {HintCase{"obs_x264", "CBR", true}, HintCase{"obs_x264", "VBR", true}, HintCase{"obs_x264", "CRF", false}, + HintCase{"obs_nvenc_h264_tex", "CQVBR", true}, HintCase{"obs_nvenc_h264_tex", "VBR", true}, + HintCase{"obs_nvenc_h264_tex", "CQP", false}, HintCase{"obs_qsv11_v2", "VBR", false}}) { TestRelay relay; reset(relay.Url()); - g_rate_control = mode; + g_encoder_id = c.id; + g_rate_control = c.mode; { MoQOutput o(nullptr, OUTPUT); CHECK(o.Start()); @@ -613,7 +635,8 @@ int main() CHECK(catalog->audio.size() == 1); for (const auto &[name, video] : catalog->video) { CHECK(video.coded.has_value()); - CHECK(video.bitrate.has_value() == (g_rate_control == "CBR")); + CHECK(video.bitrate.has_value() == c.hint); + CHECK(!c.hint || *video.bitrate == 8'000'000); } } @@ -626,7 +649,7 @@ int main() // The destructor stops too, which OBS ignores for an output already stopped. CHECK(signalCount() == 2); } - printf("publishes, and only CBR hints its bitrate: ok\n"); + printf("publishes, and hints the peak its encoder holds: ok\n"); // OBS reads the byte total as this stream's, so a stopped output that starts // again counts from zero. @@ -651,15 +674,21 @@ int main() // Video follows the grant only when the encoder retunes live and the bitrate // drives it; every track reserves either way once the session connects. struct FollowCase { + const char *id; const char *rate_control; uint32_t caps; bool follows; }; - for (const auto &c : {FollowCase{"CBR", OBS_ENCODER_CAP_DYN_BITRATE, true}, - FollowCase{"vbr", OBS_ENCODER_CAP_DYN_BITRATE, true}, - FollowCase{"CQP", OBS_ENCODER_CAP_DYN_BITRATE, false}, FollowCase{"CBR", 0, false}}) { + for (const auto &c : {FollowCase{"obs_x264", "CBR", OBS_ENCODER_CAP_DYN_BITRATE, true}, + FollowCase{"obs_x264", "vbr", OBS_ENCODER_CAP_DYN_BITRATE, true}, + FollowCase{"obs_nvenc_h264_tex", "CQVBR", OBS_ENCODER_CAP_DYN_BITRATE, true}, + FollowCase{"obs_qsv11_v2", "vbr", OBS_ENCODER_CAP_DYN_BITRATE, true}, + FollowCase{"obs_x264", "CQP", OBS_ENCODER_CAP_DYN_BITRATE, false}, + FollowCase{"obs_nvenc_h264_tex", "CQP", OBS_ENCODER_CAP_DYN_BITRATE, false}, + FollowCase{"obs_x264", "CBR", 0, false}}) { TestRelay relay; reset(relay.Url()); + g_encoder_id = c.id; g_rate_control = c.rate_control; g_encoder_caps = c.caps; MoQOutput o(nullptr, OUTPUT); @@ -703,10 +732,34 @@ int main() o.Stop(); const auto applied = updates(); CHECK(!applied.empty()); - CHECK(!applied.empty() && applied.back() == std::make_pair(VIDEO_ENCODER, 8000LL)); + CHECK(!applied.empty() && applied.back() == (Update{VIDEO_ENCODER, "bitrate", 8000})); } printf("stop restores the configured bitrate: ok\n"); + // Capped VBR moves its peak: NVENC's constant quality ignores "bitrate" and holds + // its ceiling in "max_bitrate", for the grant and for the restore alike. + { + TestRelay relay; + reset(relay.Url()); + g_encoder_id = "obs_nvenc_h264_tex"; + g_rate_control = "CQVBR"; + MoQOutput o(nullptr, OUTPUT); + CHECK(o.Start()); + CHECK(WaitFor([&] { return o.IsLiveSession(); })); + auto keyframe = TestH264Keyframe(); + auto video = videoPacket(keyframe, 0); + o.Data(&video); + MoQOutputStatsTest::Retarget(o, VIDEO_ENCODER, moq::RateTarget::kEnabled{800'000}); + o.Stop(); + const auto applied = updates(); + CHECK(applied.size() >= 2); + if (applied.size() >= 2) { + CHECK(applied[applied.size() - 2] == (Update{VIDEO_ENCODER, "max_bitrate", 800})); + CHECK(applied.back() == (Update{VIDEO_ENCODER, "max_bitrate", 8000})); + } + } + printf("capped VBR retunes its peak setting: ok\n"); + // Two video encoders form a ladder: the higher rung sits one priority below the // lower, and a disabled rung leaves the catalog disabled, dropping its packets // until a keyframe after the grant funds it again. No encoder follows here, so diff --git a/doc/bin/obs.md b/doc/bin/obs.md index ddf5c2bd888..80b9b85a42b 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -40,11 +40,21 @@ settings** off. A keyframe interval shorter than 2 s stays. Both tune x264, NVENC, Quick Sync, AMF, VA-API, and VideoToolbox, and leave any other encoder's settings alone. +The dock's Custom settings profiles run x264 and NVENC at constant quality under +a peak (capped VBR): Quality peaks at 8 Mbps and Performance at 2.5 Mbps, which +a complex scene reaches and a calm one stays well under. Other encoders run CBR +at that rate, since their quality modes carry no hard peak (Quick Sync's ICQ, +AMF's QVBR) or have not been checked (VA-API, VideoToolbox). **Use OBS Output +settings** keeps the rate control OBS configured. The catalog's `bitrate` is that +peak (under CBR, the bitrate), never the measured rate, so viewers price the +rendition by what it can send. + The video bitrate follows the connection's bandwidth estimate, with the -configured bitrate as the ceiling: it drops as soon as the uplink narrows and -climbs back over a few seconds. Audio holds its configured bitrate, and video -gets what is left. Only encoders that can retune while live, with CBR, VBR, or -ABR rate control, follow; CQP and CRF keep their setting. The dock's Stats tab +configured bitrate (the peak, under capped VBR) as the ceiling: it drops as soon +as the uplink narrows and climbs back over a few seconds. Audio holds its +configured bitrate, and video gets what is left. Only encoders that can retune +while live, with CBR, VBR, ABR, or NVENC's CQVBR rate control, follow; CQP and +CRF keep their setting. The dock's Stats tab shows the current video target beside the configured rate. An encoder shared with a recording follows too, so record with a separate encoder to keep the recording at the full rate. @@ -52,7 +62,7 @@ recording at the full rate. ## Simulcast renditions Every video encoder on OBS's stream output is its own rendition of the -broadcast, with its size, codec, and (under CBR) configured bitrate in the +broadcast, with its size, codec, and (under CBR or capped VBR) peak bitrate in the catalog, so `` picks between them. OBS adds encoders from its WHIP simulcast layer count, `Stream1` / `WHIPSimulcastTotalLayers` in the profile, whatever the service: `N` layers add `N - 1` copies of the stream encoder, diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index 6cf3554bc05..96d949c177e 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -1,25 +1,38 @@ -# [S] OBS defaults to capped VBR +# [S] OBS runs capped VBR on VideoToolbox and VA-API ## Goal -The OBS plugin's dock profiles configure the user's encoder for capped VBR -(constant quality with the profile's bitrate as the peak) instead of CBR, the -catalog `bitrate` carries that peak for a VBR encoder instead of the measured -running maximum, and dynamic bitrate moves the peak. +The OBS plugin's dock profiles run VideoToolbox (macOS) and VA-API encoders at +constant quality under the profile's peak, where that peak is measured to hold, +instead of the CBR they fall back to today. ## Plan The epic's decisions apply: quality mode with a peak where honored, otherwise CBR. -Today `cpp/obs/src/moq-dock.cpp` sets `rate_control = "CBR"` with -2500 kbps, or 8000/2500 for the Quality/Performance profiles, and -`moq-output.cpp` supplies a catalog bitrate only for CBR, so a VBR stream -advertises its measured peak, which starts low on a calm opening scene. -Candidates: x264's `VBR` (CRF under a VBV max rate) and NVENC's `VBR` or `CQVBR` -with `max_bitrate`; check each encoder's settings keys and the -`OBS_ENCODER_CAP_DYN_BITRATE` path. The profile bitrates follow the -default cap formula (`Config::resolved_bitrate` in -`rs/moq-video/src/encode/encoder.rs`) for their resolution. +Done: `ApplyEncoderRate` in `cpp/obs/src/moq-encoder-rate.h` runs x264 as +`VBR` (CRF under a VBV max rate) and NVENC as `CQVBR` with `max_bitrate`, and +the output prices, advertises, and retunes that peak (NVENC under `max_bitrate`). +Quick Sync (ICQ has no max rate) and AMF (QVBR sets no peak) stay CBR for good. + +Remaining, each needing hardware to measure that the peak holds: + +- VideoToolbox: `rate_control` `CRF` (Apple Silicon only) with `limit_bitrate`, + `max_bitrate` and `max_bitrate_window`, which becomes a `DataRateLimits` hint + that may exceed the cap; an Intel Mac falls back to ABR. `vt_update` only + re-applies on a `bitrate` change, so a retune sets `bitrate` and `max_bitrate` + together. +- VA-API: `QVBR` where the driver lists it (`vaapi_device_rc_supported`), with + `maxrate` as the peak; check what the driver does with `bitrate` and whether + the encoder advertises `OBS_ENCODER_CAP_DYN_BITRATE` (it does not today). + +Whatever measures as not holding stays CBR. Extend `EncoderPeakKey` and +`ApplyEncoderRate`; the output follows from them. Public API: none. Wire: none. + +## Hosts + +- macos - VideoToolbox's rate limit can only be measured on a Mac +- linux - VA-API's quality mode depends on the driver, so it is measured on one diff --git a/sh/obs/unit.sh b/sh/obs/unit.sh index bfe89fbbd4b..14bb197fd73 100755 --- a/sh/obs/unit.sh +++ b/sh/obs/unit.sh @@ -64,7 +64,7 @@ for name in moq-audio-encoder moq-output moq-settings moq-source obs-moq; do -o "$out/$name-test" "${sources[@]}" "$out/moq.o" $moq_libs TSAN_OPTIONS="halt_on_error=1 suppressions=$PWD/test/tsan.supp" "$out/$name-test" done -for name in moq-quality-defaults moq-dock-stop moq-error moq-encoder-latency moq-dial moq-spark; do +for name in moq-quality-defaults moq-dock-stop moq-error moq-encoder-latency moq-encoder-rate moq-dial moq-spark; do "$cxx" "${flags[@]}" "${includes[@]}" \ -o "$out/$name-test" "test/$name-test.cpp" TSAN_OPTIONS="halt_on_error=1 suppressions=$PWD/test/tsan.supp" "$out/$name-test" From 70aa55110c86797ae7022925c4f3a0eca6aa4f79 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 13:08:52 -0800 Subject: [PATCH 03/11] docs(quest): record the maintainer's decisions in the OBS capped VBR quest Co-Authored-By: Claude Sonnet 5.5 --- quest/m1/video-rate/obs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index 96d949c177e..d86e79bca9b 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -27,7 +27,10 @@ Remaining, each needing hardware to measure that the peak holds: `maxrate` as the peak; check what the driver does with `bitrate` and whether the encoder advertises `OBS_ENCODER_CAP_DYN_BITRATE` (it does not today). -Whatever measures as not holding stays CBR. Extend `EncoderPeakKey` and +Whatever measures as not holding stays CBR. Decided by the maintainer: "Use +OBS Output settings" in Simple mode stays CBR, and every encoder keeps its own +default quality level (x264 CRF 23, NVENC target quality 20) until the VMAF +harness ([quest/m9/video-quality](/quest/m9/video-quality/README.md)) picks one. Extend `EncoderPeakKey` and `ApplyEncoderRate`; the output follows from them. Public API: none. Wire: none. From e14206c24839e40987b807167e5a201b4da36cac Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 13:15:33 -0800 Subject: [PATCH 04/11] fix(obs): NVENC plain VBR retunes its average with its peak Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 23 +++++++++++++--- cpp/obs/src/moq-output.cpp | 19 +++++++++---- cpp/obs/src/moq-output.h | 3 ++ cpp/obs/test/moq-encoder-rate-test.cpp | 12 ++++++++ cpp/obs/test/moq-output-test.cpp | 38 ++++++++++++++++++++++---- 5 files changed, 79 insertions(+), 16 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index cd20715e717..4003df7650a 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -4,14 +4,21 @@ #include #include #include +#include + +inline std::string Upper(std::string text) +{ + for (char &c : text) + c = static_cast(std::toupper(static_cast(c))); + return text; +} // The setting that holds the hard peak an encoder honors under `rate_control`, or null // when it has none (CQP, CRF, ICQ, or a mode that only averages). The peak is what // reservations, the catalog, and dynamic bitrate price a rendition at. inline const char *EncoderPeakKey(const std::string &id, std::string rate_control) { - for (char &c : rate_control) - c = static_cast(std::toupper(static_cast(c))); + rate_control = Upper(std::move(rate_control)); // CBR holds the encoder at its bitrate, so that is also its peak. if (rate_control == "CBR") return "bitrate"; @@ -29,16 +36,24 @@ inline const char *EncoderPeakKey(const std::string &id, std::string rate_contro struct MoQPeak { const char *key = nullptr; long long kbps = 0; + // The average NVENC's plain VBR holds beside its peak, which must stay at or below it, + // or 0 when the encoder has none. + long long average_kbps = 0; }; // The peak these encoder settings configure, with a null key when they configure none. inline MoQPeak EncoderPeak(const std::string &id, obs_data_t *settings) { - const char *key = EncoderPeakKey(id, obs_data_get_string(settings, "rate_control")); + const std::string rate_control = obs_data_get_string(settings, "rate_control"); + const char *key = EncoderPeakKey(id, rate_control); if (!key) return {}; const long long kbps = obs_data_get_int(settings, key); - return kbps > 0 ? MoQPeak{key, kbps} : MoQPeak{}; + if (kbps <= 0) + return {}; + // NVENC's plain VBR averages at "bitrate" beside its peak in "max_bitrate". + const bool averaged = std::string(key) == "max_bitrate" && Upper(rate_control) == "VBR"; + return {key, kbps, averaged ? obs_data_get_int(settings, "bitrate") : 0}; } // Configures `settings` to run `id` at constant quality under a peak of `cap_kbps`, where diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index cf8c9e32853..e9b46666fa0 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -75,11 +75,15 @@ const moq::Error *PhaseFailure(const moq::ConnectionPhase &phase) // Retune `encoder` to `bitrate_bps` in its `key` setting, the way OBS's own RTMP dynamic // bitrate does. The key is where the encoder holds its peak: "bitrate" for most, but -// "max_bitrate" for NVENC's constant quality. -void SetBitrate(obs_encoder_t *encoder, const char *key, uint64_t bitrate_bps) +// "max_bitrate" for NVENC's constant quality. An encoder that also averages (NVENC's plain +// VBR) keeps that average at `average_kbps`, lowered to the peak so the pair stays valid. +void SetBitrate(obs_encoder_t *encoder, const char *key, uint64_t bitrate_bps, long long average_kbps) { OBSDataAutoRelease settings = obs_data_create(); - obs_data_set_int(settings, key, (long long)(bitrate_bps / 1000)); + const long long peak_kbps = (long long)(bitrate_bps / 1000); + obs_data_set_int(settings, key, peak_kbps); + if (average_kbps > 0) + obs_data_set_int(settings, "bitrate", std::min(average_kbps, peak_kbps)); obs_encoder_update(encoder, settings); } @@ -415,6 +419,7 @@ void MoQOutput::Reset() OBSEncoder encoder; const char *key; uint64_t bitrate_bps; + long long average_kbps; }; std::vector restore; @@ -424,7 +429,8 @@ void MoQOutput::Reset() track.producer->finish(); if (track.rate && track.applied_bps != track.bitrate_bps) { if (OBSEncoder strong = OBSGetStrongRef(track.encoder)) - restore.push_back({std::move(strong), track.rate_key, track.bitrate_bps}); + restore.push_back( + {std::move(strong), track.rate_key, track.bitrate_bps, track.average_kbps}); } } video_tracks.clear(); @@ -461,7 +467,7 @@ void MoQOutput::Reset() lock.unlock(); for (auto &r : restore) - SetBitrate(r.encoder, r.key, r.bitrate_bps); + SetBitrate(r.encoder, r.key, r.bitrate_bps, r.average_kbps); } std::string MoQOutput::GetInstance() @@ -762,7 +768,7 @@ void MoQOutput::VideoData(struct encoder_packet *packet) void MoQOutput::Retarget(obs_encoder_t *encoder, Track &track, const moq::RateTarget &target) { if (const auto *enabled = std::get_if(&target.get_variant())) { - SetBitrate(encoder, track.rate_key, enabled->bitrate_bps); + SetBitrate(encoder, track.rate_key, enabled->bitrate_bps, track.average_kbps); track.applied_bps = enabled->bitrate_bps; track.enabled = true; return; @@ -918,6 +924,7 @@ void MoQOutput::VideoInit(obs_encoder_t *encoder) const bool dynamic = obs_encoder_get_caps(encoder) & OBS_ENCODER_CAP_DYN_BITRATE; if (dynamic && (peak.key || BitrateDriven(rate_control))) { entry.rate_key = peak.key ? peak.key : "bitrate"; + entry.average_kbps = peak.average_kbps; entry.rate = moq::RateControl::init(moq::RatePolicy{entry.bitrate_bps, lower_bps}); entry.applied_bps = entry.bitrate_bps; entry.encoder = OBSGetWeakRef(encoder); diff --git a/cpp/obs/src/moq-output.h b/cpp/obs/src/moq-output.h index 4d3e0c60988..c1c15cd5d00 100644 --- a/cpp/obs/src/moq-output.h +++ b/cpp/obs/src/moq-output.h @@ -132,6 +132,9 @@ class MoQOutput { OBSWeakEncoder encoder; // The encoder setting that holds its peak, which following the grant retunes. const char *rate_key = "bitrate"; + // The average NVENC's plain VBR holds beside its peak, or 0: following lowers it + // with the peak and Reset() restores it. + long long average_kbps = 0; // The bitrate the encoder was last told, which Reset() restores when it moved. uint64_t applied_bps = 0; // Whether the last target enabled this rendition. diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index e97ae03637f..ff9c66b0ce6 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -70,6 +70,18 @@ int main() } assert(!EncoderPeakKey("obs_qsv11_v2", "VBR")); + // NVENC's plain VBR averages beside its peak; CQVBR and CBR have no average to keep. + obs_data_t vbr; + obs_data_set_string(&vbr, "rate_control", "VBR"); + obs_data_set_int(&vbr, "bitrate", 6000); + obs_data_set_int(&vbr, "max_bitrate", 8000); + const MoQPeak averaged = EncoderPeak("obs_nvenc_h264_tex", &vbr); + assert(averaged.kbps == 8000 && averaged.average_kbps == 6000); + assert(EncoderPeak("obs_x264", &x264).average_kbps == 0); + obs_data_t cq; + assert(ApplyEncoderRate("obs_nvenc_h264_tex", &cq, 2500)); + assert(EncoderPeak("obs_nvenc_h264_tex", &cq).average_kbps == 0); + // A peak of 0 is none: NVENC reads it as the driver's own limit. obs_data_t unbounded; obs_data_set_string(&unbounded, "rate_control", "CQVBR"); diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index ec9d1ba06d1..9c4850a4b5f 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -218,10 +218,9 @@ long long obs_data_get_int(obs_data_t *settings, const char *) return settings == reinterpret_cast(MID_ENCODER) ? 4000 : 8000; } -// The settings a retune builds carry only the one rate, so the stub is that setting. +// The settings a retune builds carry only its rates, so the stub is those settings. struct obs_data { - std::string key; - long long bitrate = 0; + std::vector> rates; }; obs_data_t *obs_data_create() @@ -231,8 +230,7 @@ obs_data_t *obs_data_create() void obs_data_set_int(obs_data_t *data, const char *key, long long value) { - data->key = key; - data->bitrate = value; + data->rates.emplace_back(key, value); } uint32_t obs_encoder_get_caps(const obs_encoder_t *) @@ -243,7 +241,8 @@ uint32_t obs_encoder_get_caps(const obs_encoder_t *) void obs_encoder_update(obs_encoder_t *encoder, obs_data_t *settings) { std::lock_guard lock(g_updates_mutex); - g_updates.emplace_back(encoder, settings->key, settings->bitrate); + for (const auto &[key, kbps] : settings->rates) + g_updates.emplace_back(encoder, key, kbps); delete settings; } @@ -760,6 +759,33 @@ int main() } printf("capped VBR retunes its peak setting: ok\n"); + // NVENC's plain VBR also averages at "bitrate", which must not exceed the lowered peak + // or the encoder rejects the pair, so the grant and the restore move both. + { + TestRelay relay; + reset(relay.Url()); + g_encoder_id = "obs_nvenc_h264_tex"; + g_rate_control = "VBR"; + MoQOutput o(nullptr, OUTPUT); + CHECK(o.Start()); + CHECK(WaitFor([&] { return o.IsLiveSession(); })); + auto keyframe = TestH264Keyframe(); + auto video = videoPacket(keyframe, 0); + o.Data(&video); + MoQOutputStatsTest::Retarget(o, VIDEO_ENCODER, moq::RateTarget::kEnabled{800'000}); + o.Stop(); + const auto applied = updates(); + CHECK(applied.size() >= 4); + if (applied.size() >= 4) { + const auto tail = applied.size() - 4; + CHECK(applied[tail] == (Update{VIDEO_ENCODER, "max_bitrate", 800})); + CHECK(applied[tail + 1] == (Update{VIDEO_ENCODER, "bitrate", 800})); + CHECK(applied[tail + 2] == (Update{VIDEO_ENCODER, "max_bitrate", 8000})); + CHECK(applied[tail + 3] == (Update{VIDEO_ENCODER, "bitrate", 8000})); + } + } + printf("plain VBR retunes its average with its peak: ok\n"); + // Two video encoders form a ladder: the higher rung sits one priority below the // lower, and a disabled rung leaves the catalog disabled, dropping its packets // until a keyframe after the grant funds it again. No encoder follows here, so From 44ae3c68409bb3ad0d6e631fb3c7c10ddb29a0db Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 13:48:21 -0800 Subject: [PATCH 05/11] fix(obs): x264opts that set a rate replace the inferred peak Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 22 ++++++++++++++++++++++ cpp/obs/test/moq-encoder-rate-test.cpp | 10 ++++++++++ quest/m1/video-rate/obs.md | 10 ++++++---- 3 files changed, 38 insertions(+), 4 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index 4003df7650a..eb05d834432 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -3,6 +3,7 @@ #include #include +#include #include #include @@ -32,6 +33,24 @@ inline const char *EncoderPeakKey(const std::string &id, std::string rate_contro return nullptr; } +// Whether x264's advanced options set a rate of their own. OBS applies `x264opts` after its +// rate parameters, so a `vbv-maxrate` replaces the peak, `bitrate` replaces the rate mode, +// and `qp` drops the VBV, and the configured bitrate no longer bounds the encoder. +inline bool X264OptionsOverrideRate(const std::string &options) +{ + std::istringstream input(options); + std::string option; + while (input >> option) { + std::string name = option.substr(0, option.find('=')); + for (char &c : name) + if (c == '_') + c = '-'; + if (name == "vbv-maxrate" || name == "bitrate" || name == "qp") + return true; + } + return false; +} + // An encoder's hard peak in kbps and the setting that holds it. struct MoQPeak { const char *key = nullptr; @@ -48,6 +67,9 @@ inline MoQPeak EncoderPeak(const std::string &id, obs_data_t *settings) const char *key = EncoderPeakKey(id, rate_control); if (!key) return {}; + // A peak the user's own x264 options replace is not one we can price. + if (id == "obs_x264" && X264OptionsOverrideRate(obs_data_get_string(settings, "x264opts"))) + return {}; const long long kbps = obs_data_get_int(settings, key); if (kbps <= 0) return {}; diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index ff9c66b0ce6..6688855ecac 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -42,6 +42,16 @@ int main() assert(rate_control(x264) == "VBR" && obs_data_get_int(&x264, "bitrate") == 8000); assert(EncoderPeak("obs_x264", &x264).kbps == 8000); + // x264opts that set a rate of their own replace the peak, so none is advertised; + // options that do not touch the rate leave it. + obs_data_set_string(&x264, "x264opts", "tune=film vbv-bufsize=4000 crf=20"); + assert(EncoderPeak("obs_x264", &x264).kbps == 8000); + for (const char *options : {"vbv-maxrate=12000", "tune=film vbv_maxrate=0", "qp=20", "bitrate=4000"}) { + obs_data_set_string(&x264, "x264opts", options); + assert(!EncoderPeak("obs_x264", &x264).key); + } + obs_data_set_string(&x264, "x264opts", ""); + for (const char *id : {"obs_nvenc_h264_tex", "obs_nvenc_hevc_soft", "obs_nvenc_av1_tex"}) { obs_data_t nvenc; assert(ApplyEncoderRate(id, &nvenc, 2500)); diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index d86e79bca9b..3bb9391272a 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -21,8 +21,9 @@ Remaining, each needing hardware to measure that the peak holds: - VideoToolbox: `rate_control` `CRF` (Apple Silicon only) with `limit_bitrate`, `max_bitrate` and `max_bitrate_window`, which becomes a `DataRateLimits` hint that may exceed the cap; an Intel Mac falls back to ABR. `vt_update` only - re-applies on a `bitrate` change, so a retune sets `bitrate` and `max_bitrate` - together. + re-applies on a `bitrate` change, so `SetBitrate` must write `bitrate` beside + `max_bitrate` and clamp it to the granted peak, as it does for NVENC's plain + VBR (`MoQPeak::average_kbps`); `Reset()` restores both. - VA-API: `QVBR` where the driver lists it (`vaapi_device_rc_supported`), with `maxrate` as the peak; check what the driver does with `bitrate` and whether the encoder advertises `OBS_ENCODER_CAP_DYN_BITRATE` (it does not today). @@ -30,8 +31,9 @@ Remaining, each needing hardware to measure that the peak holds: Whatever measures as not holding stays CBR. Decided by the maintainer: "Use OBS Output settings" in Simple mode stays CBR, and every encoder keeps its own default quality level (x264 CRF 23, NVENC target quality 20) until the VMAF -harness ([quest/m9/video-quality](/quest/m9/video-quality/README.md)) picks one. Extend `EncoderPeakKey` and -`ApplyEncoderRate`; the output follows from them. +harness ([quest/m9/video-quality](/quest/m9/video-quality/README.md)) picks one. Extend `EncoderPeakKey`, +`EncoderPeak`, and `ApplyEncoderRate` for the mode, and the retune and restore +in `moq-output.cpp` for the setting a grant writes. Public API: none. Wire: none. From ccc2471f71d34e90e28d27eeaa2baf029e70b827 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 14:51:57 -0800 Subject: [PATCH 06/11] feat(obs): the output owns the cap on every video encoder it starts The plugin writes the cap before OBS initializes each encoder and replaces any conflicting user rate option with a logged warning, so the catalog advertises exactly the cap it set rather than one inferred from the user's settings. Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 164 +++++++++++++++++++------ cpp/obs/src/moq-output.cpp | 30 +++++ cpp/obs/test/moq-encoder-rate-test.cpp | 101 +++++++++++++-- cpp/obs/test/moq-output-test.cpp | 56 ++++++--- doc/bin/obs.md | 48 +++++--- quest/m1/video-rate/obs.md | 20 +-- 6 files changed, 327 insertions(+), 92 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index eb05d834432..35553311531 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -6,6 +6,7 @@ #include #include #include +#include inline std::string Upper(std::string text) { @@ -33,24 +34,6 @@ inline const char *EncoderPeakKey(const std::string &id, std::string rate_contro return nullptr; } -// Whether x264's advanced options set a rate of their own. OBS applies `x264opts` after its -// rate parameters, so a `vbv-maxrate` replaces the peak, `bitrate` replaces the rate mode, -// and `qp` drops the VBV, and the configured bitrate no longer bounds the encoder. -inline bool X264OptionsOverrideRate(const std::string &options) -{ - std::istringstream input(options); - std::string option; - while (input >> option) { - std::string name = option.substr(0, option.find('=')); - for (char &c : name) - if (c == '_') - c = '-'; - if (name == "vbv-maxrate" || name == "bitrate" || name == "qp") - return true; - } - return false; -} - // An encoder's hard peak in kbps and the setting that holds it. struct MoQPeak { const char *key = nullptr; @@ -67,9 +50,6 @@ inline MoQPeak EncoderPeak(const std::string &id, obs_data_t *settings) const char *key = EncoderPeakKey(id, rate_control); if (!key) return {}; - // A peak the user's own x264 options replace is not one we can price. - if (id == "obs_x264" && X264OptionsOverrideRate(obs_data_get_string(settings, "x264opts"))) - return {}; const long long kbps = obs_data_get_int(settings, key); if (kbps <= 0) return {}; @@ -78,24 +58,132 @@ inline MoQPeak EncoderPeak(const std::string &id, obs_data_t *settings) return {key, kbps, averaged ? obs_data_get_int(settings, "bitrate") : 0}; } -// Configures `settings` to run `id` at constant quality under a peak of `cap_kbps`, where -// the encoder honors one, and at CBR at that rate where it does not, so it never -// exceeds the rate a viewer priced it at. Returns whether the quality mode took. -// The quality level is the encoder's own default. -inline bool ApplyEncoderRate(const std::string &id, obs_data_t *settings, long long cap_kbps) +inline bool IsNvenc(const std::string &id) { - obs_data_set_int(settings, "bitrate", cap_kbps); - if (id == "obs_x264") { - obs_data_set_string(settings, "rate_control", "VBR"); - return true; + return id.rfind("obs_nvenc_", 0) == 0; +} + +// The cap in kbps the settings name: NVENC's own peak when its VBR or constant quality +// sets one, otherwise the bitrate. 0 when the settings name none. +inline long long ConfiguredCapKbps(const std::string &id, obs_data_t *settings) +{ + if (IsNvenc(id)) { + const std::string rate_control = Upper(obs_data_get_string(settings, "rate_control")); + const long long peak = obs_data_get_int(settings, "max_bitrate"); + if ((rate_control == "VBR" || rate_control == "CQVBR") && peak > 0) + return peak; + } + return obs_data_get_int(settings, "bitrate"); +} + +// The options in `x264opts` that set a rate of their own: OBS applies them after its rate +// parameters, so `vbv-maxrate` and `vbv-bufsize` replace the VBV (0 disables it), `bitrate` +// replaces the rate mode, and `qp` drops the VBV for constant QP. +inline std::string StripX264RateOptions(const std::string &options, std::vector *removed) +{ + std::istringstream input(options); + std::string kept; + std::string option; + while (input >> option) { + std::string name = option.substr(0, option.find('=')); + for (char &c : name) + if (c == '_') + c = '-'; + if (name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp") { + removed->push_back(option); + continue; + } + kept += (kept.empty() ? "" : " ") + option; } - if (id.rfind("obs_nvenc_", 0) == 0) { - obs_data_set_string(settings, "rate_control", "CQVBR"); - obs_data_set_int(settings, "max_bitrate", cap_kbps); - return true; + return kept; +} + +// What EnforceCap changed. +struct MoQCap { + // Whether `write` holds anything the encoder's settings did not already say. + bool changed = false; + // The user's rate settings it replaced, each described for a log line. + std::vector replaced; +}; + +// Makes `id` hold `cap_kbps` as its hard peak, writing what differs from `read` into +// `write` (the same settings, to rewrite them in place). The cap is the plugin's: it +// replaces any rate the user set that would exceed it, and says which in `replaced`. +// - x264 keeps CBR and otherwise runs VBR (CRF under a VBV whose max rate and buffer are +// the bitrate), with `x264opts` stripped of the options that set a rate of their own. +// - NVENC keeps CBR and VBR, with `max_bitrate` at the cap and the average under it, and +// otherwise runs CQVBR (constant quality under `max_bitrate`). +// - Everything else runs CBR at the cap: its quality modes carry no hard peak, or depend +// on a driver or a Mac to check. +// The quality level is the encoder's own default. An unset rate mode (a fresh dock profile) +// takes the quality mode where there is one without being reported as replaced. +inline MoQCap EnforceCap(const std::string &id, obs_data_t *read, obs_data_t *write, long long cap_kbps) +{ + MoQCap result; + const std::string before = obs_data_get_string(read, "rate_control"); + const std::string mode = Upper(before); + const long long average = obs_data_get_int(read, "bitrate"); + const std::string x264opts = obs_data_get_string(read, "x264opts"); + const bool use_bufsize = obs_data_get_bool(read, "use_bufsize"); + + auto set_int = [&](const char *key, long long value) { + if (obs_data_get_int(read, key) == value) + return; + obs_data_set_int(write, key, value); + result.changed = true; + }; + auto set_mode = [&](const char *want) { + if (mode == want) + return; + obs_data_set_string(write, "rate_control", want); + result.changed = true; + if (!before.empty()) + result.replaced.push_back("rate_control " + before + " -> " + want); + }; + + if (id == "obs_x264") { + set_mode(mode == "CBR" ? "CBR" : "VBR"); + set_int("bitrate", cap_kbps); + // A buffer of its own can hold a burst past the cap; unset, OBS sizes it to the bitrate. + if (use_bufsize) { + obs_data_set_bool(write, "use_bufsize", false); + result.changed = true; + result.replaced.push_back("use_bufsize"); + } + std::vector removed; + const std::string kept = StripX264RateOptions(x264opts, &removed); + if (!removed.empty()) { + obs_data_set_string(write, "x264opts", kept.c_str()); + result.changed = true; + for (const std::string &option : removed) + result.replaced.push_back("x264opts " + option); + } + } else if (IsNvenc(id)) { + set_mode(mode == "CBR" || mode == "VBR" ? mode.c_str() : "CQVBR"); + // CBR's peak is its bitrate and constant quality ignores it; VBR averages under its peak. + if (mode == "CBR") { + set_int("bitrate", cap_kbps); + } else { + set_int("max_bitrate", cap_kbps); + if (mode == "VBR" && average > cap_kbps) { + set_int("bitrate", cap_kbps); + result.replaced.push_back("bitrate " + std::to_string(average)); + } + } + } else { + set_mode("CBR"); + set_int("bitrate", cap_kbps); } - // Quick Sync's ICQ and AMF's QVBR carry no peak, VA-API's QVBR depends on the driver, - // and VideoToolbox's quality mode needs a Mac to check. - obs_data_set_string(settings, "rate_control", "CBR"); - return false; + return result; +} + +// Configures a fresh `settings` to run `id` at constant quality under a peak of `cap_kbps`, +// where the encoder honors one, and at CBR at that rate where it does not. Returns whether +// the quality mode took. +inline bool ApplyEncoderRate(const std::string &id, obs_data_t *settings, long long cap_kbps) +{ + obs_data_set_string(settings, "rate_control", ""); + EnforceCap(id, settings, settings, cap_kbps); + return EncoderPeakKey(id, obs_data_get_string(settings, "rate_control")) != nullptr && + Upper(obs_data_get_string(settings, "rate_control")) != "CBR"; } diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index e9b46666fa0..5a7274b22f6 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -103,6 +103,33 @@ MoQPeak PeakOf(obs_encoder_t *encoder, obs_data_t *settings) return settings && id ? EncoderPeak(id, settings) : MoQPeak{}; } +// Makes every video encoder of `output` hold the cap its settings name as a hard peak, before +// OBS initializes it: the cap the catalog advertises is the one set here, whatever else the +// user's rate settings say. An encoder whose settings name no bitrate is left alone. +void CapEncoders(obs_output_t *output) +{ + for (uint32_t idx = 0; idx < MAX_OUTPUT_VIDEO_ENCODERS; idx++) { + obs_encoder_t *encoder = obs_output_get_video_encoder2(output, idx); + const char *id = encoder ? obs_encoder_get_id(encoder) : nullptr; + OBSDataAutoRelease settings = id ? obs_encoder_get_settings(encoder) : nullptr; + if (!settings) + continue; + const long long cap = ConfiguredCapKbps(id, settings); + if (cap <= 0) { + LOG_WARNING("Video encoder %s names no bitrate, so it has no cap to advertise", id); + continue; + } + OBSDataAutoRelease patch = obs_data_create(); + const MoQCap result = EnforceCap(id, settings, patch, cap); + for (const std::string &replaced : result.replaced) + LOG_WARNING("Video encoder %s: replacing %s to hold its %lld kbps cap", id, replaced.c_str(), + cap); + if (result.changed) + obs_encoder_update(encoder, patch); + LOG_INFO("Video encoder %s capped at %lld kbps", id, cap); + } +} + // Whether `rate_control` lets the "bitrate" setting drive the encoder's output. // Encoders without the setting are bitrate-driven by construction. bool BitrateDriven(const std::string &rate_control) @@ -173,6 +200,9 @@ bool MoQOutput::Start() return false; } + // The cap goes on before initialization, which reads the settings it builds the encoder from. + CapEncoders(output); + if (!obs_output_initialize_encoders(output, 0)) { LOG_ERROR("Failed to initialize encoders"); return false; diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index 6688855ecac..357f26eb222 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -5,11 +5,22 @@ #include #include #include +#include struct obs_data { std::map> values; }; +bool obs_data_get_bool(obs_data_t *data, const char *key) +{ + auto entry = data->values.find(key); + return entry != data->values.end() && std::get(entry->second) != 0; +} +void obs_data_set_bool(obs_data_t *data, const char *key, bool value) +{ + data->values[key] = (long long)value; +} + const char *obs_data_get_string(obs_data_t *data, const char *key) { auto entry = data->values.find(key); @@ -42,15 +53,41 @@ int main() assert(rate_control(x264) == "VBR" && obs_data_get_int(&x264, "bitrate") == 8000); assert(EncoderPeak("obs_x264", &x264).kbps == 8000); - // x264opts that set a rate of their own replace the peak, so none is advertised; - // options that do not touch the rate leave it. - obs_data_set_string(&x264, "x264opts", "tune=film vbv-bufsize=4000 crf=20"); - assert(EncoderPeak("obs_x264", &x264).kbps == 8000); - for (const char *options : {"vbv-maxrate=12000", "tune=film vbv_maxrate=0", "qp=20", "bitrate=4000"}) { - obs_data_set_string(&x264, "x264opts", options); - assert(!EncoderPeak("obs_x264", &x264).key); + // x264 runs the user's CBR or VBR at the cap, and anything else as VBR. x264opts and + // a buffer of its own cannot replace the cap: the options that set a rate are dropped + // and the rest stay. + struct Case { + const char *before; + const char *after; + }; + for (const Case &c : {Case{"CBR", "CBR"}, Case{"cbr", "cbr"}, Case{"VBR", "VBR"}, Case{"CRF", "VBR"}, + Case{"ABR", "VBR"}, Case{"CQP", "VBR"}, Case{"", "VBR"}}) { + obs_data_t user, patch; + obs_data_set_string(&user, "rate_control", c.before); + obs_data_set_int(&user, "bitrate", 6000); + obs_data_set_int(&user, "buffer_size", 20000); + obs_data_set_bool(&user, "use_bufsize", true); + obs_data_set_string(&user, "x264opts", "tune=film vbv-bufsize=0 vbv_maxrate=0 qp=20 bitrate=1 crf=20"); + assert(ConfiguredCapKbps("obs_x264", &user) == 6000); + const MoQCap cap = EnforceCap("obs_x264", &user, &patch, 6000); + assert(cap.changed); + const std::string after = + patch.values.count("rate_control") ? obs_data_get_string(&patch, "rate_control") : c.before; + assert(after == c.after); + // The bitrate is already the cap; the buffer and the options are not. + assert(!patch.values.count("bitrate")); + assert(!obs_data_get_bool(&patch, "use_bufsize")); + assert(std::string(obs_data_get_string(&patch, "x264opts")) == "tune=film crf=20"); + // Four options and the buffer, plus the mode when it changed. + assert(cap.replaced.size() == 5 + (std::string(c.before) != c.after && *c.before ? 1 : 0)); } - obs_data_set_string(&x264, "x264opts", ""); + // A compliant encoder is not touched. + obs_data_t clean, nothing; + obs_data_set_string(&clean, "rate_control", "VBR"); + obs_data_set_int(&clean, "bitrate", 6000); + obs_data_set_string(&clean, "x264opts", "tune=film crf=20"); + const MoQCap untouched = EnforceCap("obs_x264", &clean, ¬hing, 6000); + assert(!untouched.changed && untouched.replaced.empty() && nothing.values.empty()); for (const char *id : {"obs_nvenc_h264_tex", "obs_nvenc_hevc_soft", "obs_nvenc_av1_tex"}) { obs_data_t nvenc; @@ -71,7 +108,51 @@ int main() assert(std::string(peak.key) == "bitrate" && peak.kbps == 8000); } - // What a user configured decides the peak, whatever the encoder. + // NVENC keeps CBR and VBR, and runs anything else as constant quality, under max_bitrate. + // Its own peak is the cap when it names one, and VBR's average stays under it. + obs_data_t vbr, vbr_patch; + obs_data_set_string(&vbr, "rate_control", "VBR"); + obs_data_set_int(&vbr, "bitrate", 9000); + obs_data_set_int(&vbr, "max_bitrate", 6000); + assert(ConfiguredCapKbps("obs_nvenc_h264_tex", &vbr) == 6000); + const MoQCap lowered = EnforceCap("obs_nvenc_h264_tex", &vbr, &vbr_patch, 6000); + assert(lowered.changed && lowered.replaced.size() == 1); + assert(obs_data_get_int(&vbr_patch, "bitrate") == 6000 && !vbr_patch.values.count("max_bitrate")); + assert(!vbr_patch.values.count("rate_control")); + // An unset peak is the bitrate. + obs_data_set_int(&vbr, "max_bitrate", 0); + assert(ConfiguredCapKbps("obs_nvenc_h264_tex", &vbr) == 9000); + obs_data_t vbr_unset_patch; + EnforceCap("obs_nvenc_h264_tex", &vbr, &vbr_unset_patch, 9000); + assert(obs_data_get_int(&vbr_unset_patch, "max_bitrate") == 9000 && !vbr_unset_patch.values.count("bitrate")); + obs_data_t cbr, cbr_patch; + obs_data_set_string(&cbr, "rate_control", "CBR"); + obs_data_set_int(&cbr, "bitrate", 5000); + obs_data_set_int(&cbr, "max_bitrate", 20000); + assert(ConfiguredCapKbps("obs_nvenc_h264_tex", &cbr) == 5000); + assert(!EnforceCap("obs_nvenc_h264_tex", &cbr, &cbr_patch, 5000).changed); + for (const char *mode : {"CQP", "lossless", ""}) { + obs_data_t user, patch; + obs_data_set_string(&user, "rate_control", mode); + obs_data_set_int(&user, "bitrate", 5000); + const MoQCap cap = EnforceCap("obs_nvenc_h264_tex", &user, &patch, 5000); + assert(cap.changed && std::string(obs_data_get_string(&patch, "rate_control")) == "CQVBR"); + assert(obs_data_get_int(&patch, "max_bitrate") == 5000); + } + + // An encoder with no quality mode that holds a peak runs CBR at the cap, whatever the user chose. + obs_data_t qsv, qsv_patch; + obs_data_set_string(&qsv, "rate_control", "ICQ"); + obs_data_set_int(&qsv, "bitrate", 3000); + const MoQCap cbr_cap = EnforceCap("obs_qsv11_v2", &qsv, &qsv_patch, 3000); + assert(cbr_cap.replaced.size() == 1 && std::string(obs_data_get_string(&qsv_patch, "rate_control")) == "CBR"); + assert(ConfiguredCapKbps("obs_qsv11_v2", &qsv) == 3000); + + // A settings with no bitrate names no cap. + obs_data_t bare; + assert(ConfiguredCapKbps("obs_x264", &bare) == 0); + + // What the settings hold decides the peak, whatever the encoder. assert(std::string(EncoderPeakKey("obs_x264", "cbr")) == "bitrate"); assert(std::string(EncoderPeakKey("obs_nvenc_h264_tex", "vbr")) == "max_bitrate"); assert(std::string(EncoderPeakKey("obs_nvenc_h264_tex", "CBR")) == "bitrate"); @@ -81,8 +162,6 @@ int main() assert(!EncoderPeakKey("obs_qsv11_v2", "VBR")); // NVENC's plain VBR averages beside its peak; CQVBR and CBR have no average to keep. - obs_data_t vbr; - obs_data_set_string(&vbr, "rate_control", "VBR"); obs_data_set_int(&vbr, "bitrate", 6000); obs_data_set_int(&vbr, "max_bitrate", 8000); const MoQPeak averaged = EncoderPeak("obs_nvenc_h264_tex", &vbr); diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index 9c4850a4b5f..081bff0e631 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -218,11 +218,25 @@ long long obs_data_get_int(obs_data_t *settings, const char *) return settings == reinterpret_cast(MID_ENCODER) ? 4000 : 8000; } -// The settings a retune builds carry only its rates, so the stub is those settings. +// The settings a retune builds carry only its rates, so the stub is those settings. Start() +// also builds a patch that caps the encoder, whose rate mode lands on the stub encoder. struct obs_data { std::vector> rates; + std::vector> strings; }; +bool obs_data_get_bool(obs_data_t *, const char *) +{ + return false; +} + +void obs_data_set_bool(obs_data_t *, const char *, bool) {} + +void obs_data_set_string(obs_data_t *data, const char *key, const char *value) +{ + data->strings.emplace_back(key, value); +} + obs_data_t *obs_data_create() { return new obs_data; @@ -243,6 +257,10 @@ void obs_encoder_update(obs_encoder_t *encoder, obs_data_t *settings) std::lock_guard lock(g_updates_mutex); for (const auto &[key, kbps] : settings->rates) g_updates.emplace_back(encoder, key, kbps); + for (const auto &[key, value] : settings->strings) { + if (key == "rate_control") + g_rate_control = value; + } delete settings; } @@ -588,19 +606,21 @@ int main() printf("retired stats never replace the accepted sample: ok\n"); // Publishes over a real session: connects, reports itself live, carries - // stats, and lands video and audio renditions in the relay's catalog. The catalog - // prices a video rendition at the hard peak its encoder holds: the bitrate under - // CBR, and the cap under x264's and NVENC's capped VBR. An encoder that only - // averages, or targets a quality, advertises none. + // stats, and lands video and audio renditions in the relay's catalog. The output + // owns the cap: whatever rate control the user chose, it leaves the encoder holding a + // hard peak (x264's and NVENC's capped VBR, CBR elsewhere) and the catalog prices the + // rendition at that peak. struct HintCase { const char *id; const char *mode; - bool hint; + const char *held; }; for (const auto &c : - {HintCase{"obs_x264", "CBR", true}, HintCase{"obs_x264", "VBR", true}, HintCase{"obs_x264", "CRF", false}, - HintCase{"obs_nvenc_h264_tex", "CQVBR", true}, HintCase{"obs_nvenc_h264_tex", "VBR", true}, - HintCase{"obs_nvenc_h264_tex", "CQP", false}, HintCase{"obs_qsv11_v2", "VBR", false}}) { + {HintCase{"obs_x264", "CBR", "CBR"}, HintCase{"obs_x264", "VBR", "VBR"}, + HintCase{"obs_x264", "CRF", "VBR"}, HintCase{"obs_x264", "ABR", "VBR"}, + HintCase{"obs_nvenc_h264_tex", "CQVBR", "CQVBR"}, HintCase{"obs_nvenc_h264_tex", "VBR", "VBR"}, + HintCase{"obs_nvenc_h264_tex", "CBR", "CBR"}, HintCase{"obs_nvenc_h264_tex", "CQP", "CQVBR"}, + HintCase{"obs_qsv11_v2", "VBR", "CBR"}, HintCase{"obs_qsv11_v2", "ICQ", "CBR"}}) { TestRelay relay; reset(relay.Url()); g_encoder_id = c.id; @@ -608,6 +628,7 @@ int main() { MoQOutput o(nullptr, OUTPUT); CHECK(o.Start()); + CHECK(g_rate_control == c.held); CHECK(WaitFor([&] { return o.IsLiveSession(); })); CHECK(o.GetConnectTime() > 0); CHECK(o.GetReconnectCount() == 0); @@ -634,8 +655,8 @@ int main() CHECK(catalog->audio.size() == 1); for (const auto &[name, video] : catalog->video) { CHECK(video.coded.has_value()); - CHECK(video.bitrate.has_value() == c.hint); - CHECK(!c.hint || *video.bitrate == 8'000'000); + CHECK(video.bitrate.has_value()); + CHECK(video.bitrate.value_or(0) == 8'000'000); } } @@ -648,7 +669,7 @@ int main() // The destructor stops too, which OBS ignores for an output already stopped. CHECK(signalCount() == 2); } - printf("publishes, and hints the peak its encoder holds: ok\n"); + printf("publishes, and hints the cap it set on its encoder: ok\n"); // OBS reads the byte total as this stream's, so a stopped output that starts // again counts from zero. @@ -670,8 +691,9 @@ int main() } printf("a restart counts bytes from zero: ok\n"); - // Video follows the grant only when the encoder retunes live and the bitrate - // drives it; every track reserves either way once the session connects. + // Video follows the grant when the encoder retunes live: the output made every + // rate control one the bitrate drives. Every track reserves either way once the + // session connects. struct FollowCase { const char *id; const char *rate_control; @@ -682,8 +704,8 @@ int main() FollowCase{"obs_x264", "vbr", OBS_ENCODER_CAP_DYN_BITRATE, true}, FollowCase{"obs_nvenc_h264_tex", "CQVBR", OBS_ENCODER_CAP_DYN_BITRATE, true}, FollowCase{"obs_qsv11_v2", "vbr", OBS_ENCODER_CAP_DYN_BITRATE, true}, - FollowCase{"obs_x264", "CQP", OBS_ENCODER_CAP_DYN_BITRATE, false}, - FollowCase{"obs_nvenc_h264_tex", "CQP", OBS_ENCODER_CAP_DYN_BITRATE, false}, + FollowCase{"obs_x264", "CQP", OBS_ENCODER_CAP_DYN_BITRATE, true}, + FollowCase{"obs_nvenc_h264_tex", "CQP", OBS_ENCODER_CAP_DYN_BITRATE, true}, FollowCase{"obs_x264", "CBR", 0, false}}) { TestRelay relay; reset(relay.Url()); @@ -710,7 +732,7 @@ int main() } o.Stop(); } - printf("video follows only a live-retunable, bitrate-driven encoder: ok\n"); + printf("video follows only a live-retunable encoder: ok\n"); // Stopping hands the configured bitrate back to an encoder the grant lowered, // so the next Start() reads the user's rate rather than the last grant. diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 80b9b85a42b..6e6d286e824 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -40,29 +40,39 @@ settings** off. A keyframe interval shorter than 2 s stays. Both tune x264, NVENC, Quick Sync, AMF, VA-API, and VideoToolbox, and leave any other encoder's settings alone. -The dock's Custom settings profiles run x264 and NVENC at constant quality under -a peak (capped VBR): Quality peaks at 8 Mbps and Performance at 2.5 Mbps, which -a complex scene reaches and a calm one stays well under. Other encoders run CBR -at that rate, since their quality modes carry no hard peak (Quick Sync's ICQ, -AMF's QVBR) or have not been checked (VA-API, VideoToolbox). **Use OBS Output -settings** keeps the rate control OBS configured. The catalog's `bitrate` is that -peak (under CBR, the bitrate), never the measured rate, so viewers price the -rendition by what it can send. - -The video bitrate follows the connection's bandwidth estimate, with the -configured bitrate (the peak, under capped VBR) as the ceiling: it drops as soon -as the uplink narrows and climbs back over a few seconds. Audio holds its -configured bitrate, and video gets what is left. Only encoders that can retune -while live, with CBR, VBR, ABR, or NVENC's CQVBR rate control, follow; CQP and -CRF keep their setting. The dock's Stats tab -shows the current video target beside the configured rate. An encoder shared -with a recording follows too, so record with a separate encoder to keep the -recording at the full rate. +Every video encoder the MoQ output starts has a cap, and the catalog's `bitrate` +is that cap, never the measured rate, so viewers price the rendition by what it +can send. The cap is the encoder's bitrate setting (NVENC's `max_bitrate` when its +VBR or constant quality sets one). The plugin writes it into the encoder itself, so +it holds whatever else the settings say: + +- x264 keeps CBR and otherwise runs constant quality (VBR) under a VBV whose max + rate and buffer are the cap. `vbv-maxrate`, `vbv-bufsize`, `bitrate`, and `qp` + in the x264 options, and a buffer size of your own, are dropped. +- NVENC keeps CBR and VBR, and otherwise runs constant quality (CQVBR), with + `max_bitrate` at the cap and VBR's average under it. +- Every other encoder runs CBR at the cap: Quick Sync's ICQ and AMF's QVBR have + no hard peak, and VA-API's and VideoToolbox's quality modes have not been + checked. + +The log names each setting of yours it replaced. An encoder shared with a +recording takes the cap too. The dock's Custom settings profiles start from +constant quality under the cap on x264 and NVENC: Quality caps at 8 Mbps and +Performance at 2.5 Mbps, which a complex scene reaches and a calm one stays well +under. **Use OBS Output settings** starts from the rate control OBS configured. + +The video bitrate follows the connection's bandwidth estimate, with the cap as +the ceiling: it drops as soon as the uplink narrows and climbs back over a few +seconds. Audio holds its configured bitrate, and video gets what is left. Only +encoders that can retune while live follow. The dock's Stats tab shows the +current video target beside the configured rate. An encoder shared with a +recording follows too, so record with a separate encoder to keep the recording +at the full rate. ## Simulcast renditions Every video encoder on OBS's stream output is its own rendition of the -broadcast, with its size, codec, and (under CBR or capped VBR) peak bitrate in the +broadcast, with its size, codec, and cap in the catalog, so `` picks between them. OBS adds encoders from its WHIP simulcast layer count, `Stream1` / `WHIPSimulcastTotalLayers` in the profile, whatever the service: `N` layers add `N - 1` copies of the stream encoder, diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index 3bb9391272a..620c5ec00b7 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -11,10 +11,16 @@ instead of the CBR they fall back to today. The epic's decisions apply: quality mode with a peak where honored, otherwise CBR. -Done: `ApplyEncoderRate` in `cpp/obs/src/moq-encoder-rate.h` runs x264 as -`VBR` (CRF under a VBV max rate) and NVENC as `CQVBR` with `max_bitrate`, and -the output prices, advertises, and retunes that peak (NVENC under `max_bitrate`). -Quick Sync (ICQ has no max rate) and AMF (QVBR sets no peak) stay CBR for good. +Done: the MoQ output owns the cap on every video encoder it starts (maintainer +decision on the PR). `EnforceCap` in `cpp/obs/src/moq-encoder-rate.h` writes it +before OBS initializes the encoder, replaces any conflicting user rate option +with a logged warning, and the catalog advertises exactly that cap: x264 keeps +CBR and otherwise runs `VBR` (CRF under a VBV whose max rate and buffer are the +bitrate, with `vbv-*`, `bitrate`, and `qp` stripped from `x264opts`), NVENC keeps +CBR and VBR and otherwise runs `CQVBR` with `max_bitrate`, and every other +encoder runs CBR at the cap. The output prices and retunes that peak (NVENC +under `max_bitrate`). Quick Sync (ICQ has no max rate) and AMF (QVBR sets no +peak) stay CBR for good. Remaining, each needing hardware to measure that the peak holds: @@ -31,9 +37,9 @@ Remaining, each needing hardware to measure that the peak holds: Whatever measures as not holding stays CBR. Decided by the maintainer: "Use OBS Output settings" in Simple mode stays CBR, and every encoder keeps its own default quality level (x264 CRF 23, NVENC target quality 20) until the VMAF -harness ([quest/m9/video-quality](/quest/m9/video-quality/README.md)) picks one. Extend `EncoderPeakKey`, -`EncoderPeak`, and `ApplyEncoderRate` for the mode, and the retune and restore -in `moq-output.cpp` for the setting a grant writes. +harness ([quest/m9/video-quality](/quest/m9/video-quality/README.md)) picks one. Extend `EnforceCap` and +`EncoderPeakKey` for the mode, and the retune and restore in `moq-output.cpp` for +the setting a grant writes. Public API: none. Wire: none. From 0e26cf88dee9266aca750ca04e1f7126ed435039 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:06:11 -0800 Subject: [PATCH 07/11] fix(obs): a lossless x264 CRF cannot drop the cap Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 17 +++++++++++++++-- cpp/obs/test/moq-encoder-rate-test.cpp | 26 +++++++++++++++++++++++--- doc/bin/obs.md | 5 +++-- quest/m1/video-rate/obs.md | 2 +- 4 files changed, 42 insertions(+), 8 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index 35553311531..640fbef6553 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -3,6 +3,7 @@ #include #include +#include #include #include #include @@ -58,6 +59,9 @@ inline MoQPeak EncoderPeak(const std::string &id, obs_data_t *settings) return {key, kbps, averaged ? obs_data_get_int(settings, "bitrate") : 0}; } +// x264's own default constant quality level, which a lossless CRF of 0 gives way to. +constexpr long long kDefaultX264Crf = 23; + inline bool IsNvenc(const std::string &id) { return id.rfind("obs_nvenc_", 0) == 0; @@ -78,7 +82,7 @@ inline long long ConfiguredCapKbps(const std::string &id, obs_data_t *settings) // The options in `x264opts` that set a rate of their own: OBS applies them after its rate // parameters, so `vbv-maxrate` and `vbv-bufsize` replace the VBV (0 disables it), `bitrate` -// replaces the rate mode, and `qp` drops the VBV for constant QP. +// replaces the rate mode, and `qp` or a `crf` of 0 (lossless) drops the VBV for constant QP. inline std::string StripX264RateOptions(const std::string &options, std::vector *removed) { std::istringstream input(options); @@ -89,7 +93,10 @@ inline std::string StripX264RateOptions(const std::string &options, std::vector< for (char &c : name) if (c == '_') c = '-'; - if (name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp") { + const size_t assign = option.find('='); + const bool lossless = name == "crf" && assign != std::string::npos && + std::atof(option.c_str() + assign + 1) <= 0; + if (name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp" || lossless) { removed->push_back(option); continue; } @@ -144,6 +151,12 @@ inline MoQCap EnforceCap(const std::string &id, obs_data_t *read, obs_data_t *wr if (id == "obs_x264") { set_mode(mode == "CBR" ? "CBR" : "VBR"); set_int("bitrate", cap_kbps); + // A CRF of 0 is lossless, which x264 runs as constant QP with no VBV. CBR ignores the setting. + if (mode != "CBR" && obs_data_get_int(read, "crf") <= 0) { + obs_data_set_int(write, "crf", kDefaultX264Crf); + result.changed = true; + result.replaced.push_back("crf 0"); + } // A buffer of its own can hold a burst past the cap; unset, OBS sizes it to the bitrate. if (use_bufsize) { obs_data_set_bool(write, "use_bufsize", false); diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index 357f26eb222..9973b967be4 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -66,8 +66,10 @@ int main() obs_data_set_string(&user, "rate_control", c.before); obs_data_set_int(&user, "bitrate", 6000); obs_data_set_int(&user, "buffer_size", 20000); + obs_data_set_int(&user, "crf", 23); obs_data_set_bool(&user, "use_bufsize", true); - obs_data_set_string(&user, "x264opts", "tune=film vbv-bufsize=0 vbv_maxrate=0 qp=20 bitrate=1 crf=20"); + obs_data_set_string(&user, "x264opts", + "tune=film vbv-bufsize=0 vbv_maxrate=0 qp=20 bitrate=1 crf=20 crf=0"); assert(ConfiguredCapKbps("obs_x264", &user) == 6000); const MoQCap cap = EnforceCap("obs_x264", &user, &patch, 6000); assert(cap.changed); @@ -78,12 +80,30 @@ int main() assert(!patch.values.count("bitrate")); assert(!obs_data_get_bool(&patch, "use_bufsize")); assert(std::string(obs_data_get_string(&patch, "x264opts")) == "tune=film crf=20"); - // Four options and the buffer, plus the mode when it changed. - assert(cap.replaced.size() == 5 + (std::string(c.before) != c.after && *c.before ? 1 : 0)); + // Five options and the buffer, plus the mode when it changed. + assert(cap.replaced.size() == 6 + (std::string(c.before) != c.after && *c.before ? 1 : 0)); } + // A lossless CRF, in the setting or the options, is a constant QP with no VBV. + obs_data_t lossless, lossless_patch; + obs_data_set_string(&lossless, "rate_control", "CRF"); + obs_data_set_int(&lossless, "bitrate", 6000); + obs_data_set_int(&lossless, "crf", 0); + const MoQCap crf0 = EnforceCap("obs_x264", &lossless, &lossless_patch, 6000); + assert(crf0.changed && obs_data_get_int(&lossless_patch, "crf") == 23); + // CBR ignores the setting, and only a zero option is lossless. + obs_data_t cbr_crf, cbr_crf_patch; + obs_data_set_string(&cbr_crf, "rate_control", "CBR"); + obs_data_set_int(&cbr_crf, "bitrate", 6000); + obs_data_set_int(&cbr_crf, "crf", 0); + obs_data_set_string(&cbr_crf, "x264opts", "crf=0.0 crf=18"); + EnforceCap("obs_x264", &cbr_crf, &cbr_crf_patch, 6000); + assert(!cbr_crf_patch.values.count("crf")); + assert(std::string(obs_data_get_string(&cbr_crf_patch, "x264opts")) == "crf=18"); + // A compliant encoder is not touched. obs_data_t clean, nothing; obs_data_set_string(&clean, "rate_control", "VBR"); + obs_data_set_int(&clean, "crf", 23); obs_data_set_int(&clean, "bitrate", 6000); obs_data_set_string(&clean, "x264opts", "tune=film crf=20"); const MoQCap untouched = EnforceCap("obs_x264", &clean, ¬hing, 6000); diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 6e6d286e824..7d7d32b6555 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -47,8 +47,9 @@ VBR or constant quality sets one). The plugin writes it into the encoder itself, it holds whatever else the settings say: - x264 keeps CBR and otherwise runs constant quality (VBR) under a VBV whose max - rate and buffer are the cap. `vbv-maxrate`, `vbv-bufsize`, `bitrate`, and `qp` - in the x264 options, and a buffer size of your own, are dropped. + rate and buffer are the cap. `vbv-maxrate`, `vbv-bufsize`, `bitrate`, `qp`, and + a lossless `crf=0` in the x264 options, a CRF of 0, and a buffer size of your + own are replaced. - NVENC keeps CBR and VBR, and otherwise runs constant quality (CQVBR), with `max_bitrate` at the cap and VBR's average under it. - Every other encoder runs CBR at the cap: Quick Sync's ICQ and AMF's QVBR have diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index 620c5ec00b7..6860ddda5bd 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -16,7 +16,7 @@ decision on the PR). `EnforceCap` in `cpp/obs/src/moq-encoder-rate.h` writes it before OBS initializes the encoder, replaces any conflicting user rate option with a logged warning, and the catalog advertises exactly that cap: x264 keeps CBR and otherwise runs `VBR` (CRF under a VBV whose max rate and buffer are the -bitrate, with `vbv-*`, `bitrate`, and `qp` stripped from `x264opts`), NVENC keeps +bitrate, with `vbv-*`, `bitrate`, `qp`, and a lossless `crf=0` stripped from `x264opts`), NVENC keeps CBR and VBR and otherwise runs `CQVBR` with `max_bitrate`, and every other encoder runs CBR at the cap. The output prices and retunes that peak (NVENC under `max_bitrate`). Quick Sync (ICQ has no max rate) and AMF (QVBR sets no From 7bcb91f44a9d9f3d3c7945a69d612d15d3e354e4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:15:54 -0800 Subject: [PATCH 08/11] fix(obs): the cap never edits x264opts, and a rate option there warns The plugin enforces the cap only through OBS's own settings keys. A rate option in x264opts that can override it logs a warning recommending the MoQ dock profiles. Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 28 ++++++++++---------------- cpp/obs/src/moq-output.cpp | 4 ++++ cpp/obs/test/moq-encoder-rate-test.cpp | 24 +++++++++++++--------- doc/bin/obs.md | 8 +++++--- quest/m1/video-rate/obs.md | 3 ++- 5 files changed, 36 insertions(+), 31 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index 640fbef6553..cb4f2501dbf 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -83,10 +83,11 @@ inline long long ConfiguredCapKbps(const std::string &id, obs_data_t *settings) // The options in `x264opts` that set a rate of their own: OBS applies them after its rate // parameters, so `vbv-maxrate` and `vbv-bufsize` replace the VBV (0 disables it), `bitrate` // replaces the rate mode, and `qp` or a `crf` of 0 (lossless) drops the VBV for constant QP. -inline std::string StripX264RateOptions(const std::string &options, std::vector *removed) +// The plugin never rewrites the text, so these can override the cap. +inline std::vector X264RateOptions(const std::string &options) { std::istringstream input(options); - std::string kept; + std::vector found; std::string option; while (input >> option) { std::string name = option.substr(0, option.find('=')); @@ -96,13 +97,10 @@ inline std::string StripX264RateOptions(const std::string &options, std::vector< const size_t assign = option.find('='); const bool lossless = name == "crf" && assign != std::string::npos && std::atof(option.c_str() + assign + 1) <= 0; - if (name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp" || lossless) { - removed->push_back(option); - continue; - } - kept += (kept.empty() ? "" : " ") + option; + if (name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp" || lossless) + found.push_back(option); } - return kept; + return found; } // What EnforceCap changed. @@ -111,13 +109,16 @@ struct MoQCap { bool changed = false; // The user's rate settings it replaced, each described for a log line. std::vector replaced; + // The `x264opts` options that can override the cap, which it leaves as the user wrote them. + std::vector overridden; }; // Makes `id` hold `cap_kbps` as its hard peak, writing what differs from `read` into // `write` (the same settings, to rewrite them in place). The cap is the plugin's: it // replaces any rate the user set that would exceed it, and says which in `replaced`. // - x264 keeps CBR and otherwise runs VBR (CRF under a VBV whose max rate and buffer are -// the bitrate), with `x264opts` stripped of the options that set a rate of their own. +// the bitrate). It writes only OBS's own settings: `x264opts` stays as the user wrote +// it, and the options in it that set a rate are reported in `overridden`. // - NVENC keeps CBR and VBR, with `max_bitrate` at the cap and the average under it, and // otherwise runs CQVBR (constant quality under `max_bitrate`). // - Everything else runs CBR at the cap: its quality modes carry no hard peak, or depend @@ -163,14 +164,7 @@ inline MoQCap EnforceCap(const std::string &id, obs_data_t *read, obs_data_t *wr result.changed = true; result.replaced.push_back("use_bufsize"); } - std::vector removed; - const std::string kept = StripX264RateOptions(x264opts, &removed); - if (!removed.empty()) { - obs_data_set_string(write, "x264opts", kept.c_str()); - result.changed = true; - for (const std::string &option : removed) - result.replaced.push_back("x264opts " + option); - } + result.overridden = X264RateOptions(x264opts); } else if (IsNvenc(id)) { set_mode(mode == "CBR" || mode == "VBR" ? mode.c_str() : "CQVBR"); // CBR's peak is its bitrate and constant quality ignores it; VBR averages under its peak. diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 5a7274b22f6..0efefdcf4f9 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -124,6 +124,10 @@ void CapEncoders(obs_output_t *output) for (const std::string &replaced : result.replaced) LOG_WARNING("Video encoder %s: replacing %s to hold its %lld kbps cap", id, replaced.c_str(), cap); + for (const std::string &option : result.overridden) + LOG_WARNING("Video encoder %s: x264opts %s can override the %lld kbps cap. Use the MoQ " + "dock's Quality or Performance profile, which hold it without x264opts.", + id, option.c_str(), cap); if (result.changed) obs_encoder_update(encoder, patch); LOG_INFO("Video encoder %s capped at %lld kbps", id, cap); diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index 9973b967be4..57d536d33e6 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -53,9 +53,9 @@ int main() assert(rate_control(x264) == "VBR" && obs_data_get_int(&x264, "bitrate") == 8000); assert(EncoderPeak("obs_x264", &x264).kbps == 8000); - // x264 runs the user's CBR or VBR at the cap, and anything else as VBR. x264opts and - // a buffer of its own cannot replace the cap: the options that set a rate are dropped - // and the rest stay. + // x264 runs the user's CBR or VBR at the cap, and anything else as VBR. A buffer of + // its own is replaced. x264opts is never rewritten: the options in it that set a rate + // are reported as overriding the cap, and the rest are not. struct Case { const char *before; const char *after; @@ -79,18 +79,20 @@ int main() // The bitrate is already the cap; the buffer and the options are not. assert(!patch.values.count("bitrate")); assert(!obs_data_get_bool(&patch, "use_bufsize")); - assert(std::string(obs_data_get_string(&patch, "x264opts")) == "tune=film crf=20"); - // Five options and the buffer, plus the mode when it changed. - assert(cap.replaced.size() == 6 + (std::string(c.before) != c.after && *c.before ? 1 : 0)); + assert(!patch.values.count("x264opts")); + assert((cap.overridden == + std::vector{"vbv-bufsize=0", "vbv_maxrate=0", "qp=20", "bitrate=1", "crf=0"})); + // The buffer, plus the mode when it changed. + assert(cap.replaced.size() == 1 + (std::string(c.before) != c.after && *c.before ? 1 : 0)); } - // A lossless CRF, in the setting or the options, is a constant QP with no VBV. + // A lossless CRF setting is a constant QP with no VBV. obs_data_t lossless, lossless_patch; obs_data_set_string(&lossless, "rate_control", "CRF"); obs_data_set_int(&lossless, "bitrate", 6000); obs_data_set_int(&lossless, "crf", 0); const MoQCap crf0 = EnforceCap("obs_x264", &lossless, &lossless_patch, 6000); assert(crf0.changed && obs_data_get_int(&lossless_patch, "crf") == 23); - // CBR ignores the setting, and only a zero option is lossless. + // CBR ignores the setting, and only a zero option is lossless; x264opts is left alone. obs_data_t cbr_crf, cbr_crf_patch; obs_data_set_string(&cbr_crf, "rate_control", "CBR"); obs_data_set_int(&cbr_crf, "bitrate", 6000); @@ -98,7 +100,8 @@ int main() obs_data_set_string(&cbr_crf, "x264opts", "crf=0.0 crf=18"); EnforceCap("obs_x264", &cbr_crf, &cbr_crf_patch, 6000); assert(!cbr_crf_patch.values.count("crf")); - assert(std::string(obs_data_get_string(&cbr_crf_patch, "x264opts")) == "crf=18"); + assert(!cbr_crf_patch.values.count("x264opts")); + assert(X264RateOptions("crf=0.0 crf=18") == std::vector{"crf=0.0"}); // A compliant encoder is not touched. obs_data_t clean, nothing; @@ -107,7 +110,8 @@ int main() obs_data_set_int(&clean, "bitrate", 6000); obs_data_set_string(&clean, "x264opts", "tune=film crf=20"); const MoQCap untouched = EnforceCap("obs_x264", &clean, ¬hing, 6000); - assert(!untouched.changed && untouched.replaced.empty() && nothing.values.empty()); + assert(!untouched.changed && untouched.replaced.empty() && untouched.overridden.empty() && + nothing.values.empty()); for (const char *id : {"obs_nvenc_h264_tex", "obs_nvenc_hevc_soft", "obs_nvenc_av1_tex"}) { obs_data_t nvenc; diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 7d7d32b6555..77d49de65b4 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -47,9 +47,11 @@ VBR or constant quality sets one). The plugin writes it into the encoder itself, it holds whatever else the settings say: - x264 keeps CBR and otherwise runs constant quality (VBR) under a VBV whose max - rate and buffer are the cap. `vbv-maxrate`, `vbv-bufsize`, `bitrate`, `qp`, and - a lossless `crf=0` in the x264 options, a CRF of 0, and a buffer size of your - own are replaced. + rate and buffer are the cap. A CRF of 0 and a buffer size of your own are + replaced. Your x264 options are never rewritten, so `vbv-maxrate`, + `vbv-bufsize`, `bitrate`, `qp`, or a lossless `crf=0` in them can override the + cap: the log warns, and the dock's Quality and Performance profiles hold it + without them. - NVENC keeps CBR and VBR, and otherwise runs constant quality (CQVBR), with `max_bitrate` at the cap and VBR's average under it. - Every other encoder runs CBR at the cap: Quick Sync's ICQ and AMF's QVBR have diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index 6860ddda5bd..2d1a7609946 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -16,7 +16,8 @@ decision on the PR). `EnforceCap` in `cpp/obs/src/moq-encoder-rate.h` writes it before OBS initializes the encoder, replaces any conflicting user rate option with a logged warning, and the catalog advertises exactly that cap: x264 keeps CBR and otherwise runs `VBR` (CRF under a VBV whose max rate and buffer are the -bitrate, with `vbv-*`, `bitrate`, `qp`, and a lossless `crf=0` stripped from `x264opts`), NVENC keeps +bitrate; `x264opts` is never rewritten, and a rate option in it logs a warning that +recommends the dock profiles), NVENC keeps CBR and VBR and otherwise runs `CQVBR` with `max_bitrate`, and every other encoder runs CBR at the cap. The output prices and retunes that peak (NVENC under `max_bitrate`). Quick Sync (ICQ has no max rate) and AMF (QVBR sets no From ee8e158295a091f70861e32ff609932721d5b5c6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 16:42:53 -0800 Subject: [PATCH 09/11] fix(obs): a running encoder keeps its settings, and must hold a cap Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 14 ++++++ cpp/obs/src/moq-output.cpp | 28 ++++++++++- cpp/obs/test/moq-encoder-rate-test.cpp | 21 ++++++++ cpp/obs/test/moq-output-test.cpp | 70 ++++++++++++++++++++++++-- doc/bin/obs.md | 8 ++- quest/m1/video-rate/obs.md | 4 +- 6 files changed, 138 insertions(+), 7 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index cb4f2501dbf..1672b28b4f4 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -80,6 +80,20 @@ inline long long ConfiguredCapKbps(const std::string &id, obs_data_t *settings) return obs_data_get_int(settings, "bitrate"); } +// The hard peak in kbps an encoder already running with `settings` holds, or 0 when it runs +// uncapped: a quality mode with no peak (CQP, CRF, ICQ), or x264's lossless CRF of 0, which +// runs as constant QP with no VBV. The settings are read as they are, never rewritten. +inline long long RunningCapKbps(const std::string &id, obs_data_t *settings) +{ + const MoQPeak peak = EncoderPeak(id, settings); + if (!peak.key) + return 0; + if (id == "obs_x264" && Upper(obs_data_get_string(settings, "rate_control")) != "CBR" && + obs_data_get_int(settings, "crf") <= 0) + return 0; + return peak.kbps; +} + // The options in `x264opts` that set a rate of their own: OBS applies them after its rate // parameters, so `vbv-maxrate` and `vbv-bufsize` replace the VBV (0 disables it), `bitrate` // replaces the rate mode, and `qp` or a `crf` of 0 (lossless) drops the VBV for constant QP. diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 0efefdcf4f9..8182e88fc65 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -106,7 +106,11 @@ MoQPeak PeakOf(obs_encoder_t *encoder, obs_data_t *settings) // Makes every video encoder of `output` hold the cap its settings name as a hard peak, before // OBS initializes it: the cap the catalog advertises is the one set here, whatever else the // user's rate settings say. An encoder whose settings name no bitrate is left alone. -void CapEncoders(obs_output_t *output) +// An encoder already running (shared with a recording that started first) cannot switch rate +// control, so its settings stay as they are and the catalog advertises the cap it runs with. +// Returns why the output cannot start, or an empty string: one that runs uncapped (CQP, CRF, +// lossless) has no cap to advertise. +std::string CapEncoders(obs_output_t *output) { for (uint32_t idx = 0; idx < MAX_OUTPUT_VIDEO_ENCODERS; idx++) { obs_encoder_t *encoder = obs_output_get_video_encoder2(output, idx); @@ -119,6 +123,20 @@ void CapEncoders(obs_output_t *output) LOG_WARNING("Video encoder %s names no bitrate, so it has no cap to advertise", id); continue; } + const bool active = obs_encoder_active(encoder); + if (active) { + const long long running = RunningCapKbps(id, settings); + if (running <= 0) + return std::string("Video encoder ") + id + + " is already running without a bitrate cap (rate control " + + obs_data_get_string(settings, "rate_control") + + "). Stop the recording first, or give it its own encoder."; + for (const std::string &option : X264RateOptions(obs_data_get_string(settings, "x264opts"))) + LOG_WARNING("Video encoder %s: x264opts %s can override its %lld kbps cap", id, + option.c_str(), running); + LOG_INFO("Video encoder %s already running, advertising its %lld kbps cap", id, running); + continue; + } OBSDataAutoRelease patch = obs_data_create(); const MoQCap result = EnforceCap(id, settings, patch, cap); for (const std::string &replaced : result.replaced) @@ -132,6 +150,7 @@ void CapEncoders(obs_output_t *output) obs_encoder_update(encoder, patch); LOG_INFO("Video encoder %s capped at %lld kbps", id, cap); } + return ""; } // Whether `rate_control` lets the "bitrate" setting drive the encoder's output. @@ -205,7 +224,12 @@ bool MoQOutput::Start() } // The cap goes on before initialization, which reads the settings it builds the encoder from. - CapEncoders(output); + const std::string uncapped = CapEncoders(output); + if (!uncapped.empty()) { + LOG_ERROR("%s", uncapped.c_str()); + obs_output_set_last_error(output, uncapped.c_str()); + return false; + } if (!obs_output_initialize_encoders(output, 0)) { LOG_ERROR("Failed to initialize encoders"); diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index 57d536d33e6..b7c628d8faa 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -53,6 +53,27 @@ int main() assert(rate_control(x264) == "VBR" && obs_data_get_int(&x264, "bitrate") == 8000); assert(EncoderPeak("obs_x264", &x264).kbps == 8000); + // A running encoder's cap is what its settings hold: its peak, or none for a quality mode + // and for x264's lossless CRF. + struct Running { + const char *id; + const char *mode; + long long crf; + long long expect; + }; + for (const Running &c : + {Running{"obs_x264", "CBR", 0, 6000}, Running{"obs_x264", "VBR", 23, 6000}, + Running{"obs_x264", "VBR", 0, 0}, Running{"obs_x264", "CRF", 23, 0}, Running{"obs_x264", "CQP", 23, 0}, + Running{"obs_nvenc_h264_tex", "CQP", 0, 0}, Running{"obs_nvenc_h264_tex", "CQVBR", 0, 7000}, + Running{"obs_qsv11_v2", "ICQ", 0, 0}}) { + obs_data_t running; + obs_data_set_string(&running, "rate_control", c.mode); + obs_data_set_int(&running, "bitrate", 6000); + obs_data_set_int(&running, "max_bitrate", 7000); + obs_data_set_int(&running, "crf", c.crf); + assert(RunningCapKbps(c.id, &running) == c.expect); + } + // x264 runs the user's CBR or VBR at the cap, and anything else as VBR. A buffer of // its own is replaced. x264opts is never rewritten: the options in it that set a rate // are reported as overriding the cap, and the rest are not. diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index 081bff0e631..20dde4bd96c 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -63,6 +63,13 @@ using Update = std::tuple; std::mutex g_updates_mutex; std::vector g_updates; std::atomic g_settings_ok{true}; +// The encoders are already running, as when a recording that started first shares them. +std::atomic g_encoder_active{false}; +// The x264 CRF and "use_bufsize" the settings report; a negative CRF is the stub's default. +std::atomic g_crf{-1}; +std::atomic g_use_bufsize{false}; +// How many times Start() or a retune rewrote an encoder's settings. +std::atomic g_update_calls{0}; // A reason Configure reports itself, for a setting the config cannot express. std::string g_settings_error; // Lets a test run something inside obs_output_signal_stop, standing in for a @@ -211,8 +218,10 @@ const char *obs_data_get_string(obs_data_t *, const char *) return g_rate_control.c_str(); } -long long obs_data_get_int(obs_data_t *settings, const char *) +long long obs_data_get_int(obs_data_t *settings, const char *key) { + if (g_crf >= 0 && std::string(key) == "crf") + return g_crf; if (settings == reinterpret_cast(LOW_ENCODER)) return 2000; return settings == reinterpret_cast(MID_ENCODER) ? 4000 : 8000; @@ -225,9 +234,14 @@ struct obs_data { std::vector> strings; }; -bool obs_data_get_bool(obs_data_t *, const char *) +bool obs_data_get_bool(obs_data_t *, const char *key) { - return false; + return g_use_bufsize && std::string(key) == "use_bufsize"; +} + +bool obs_encoder_active(const obs_encoder_t *) +{ + return g_encoder_active; } void obs_data_set_bool(obs_data_t *, const char *, bool) {} @@ -254,6 +268,7 @@ uint32_t obs_encoder_get_caps(const obs_encoder_t *) void obs_encoder_update(obs_encoder_t *encoder, obs_data_t *settings) { + g_update_calls++; std::lock_guard lock(g_updates_mutex); for (const auto &[key, kbps] : settings->rates) g_updates.emplace_back(encoder, key, kbps); @@ -345,6 +360,10 @@ void reset(std::string url) g_settings_ok = true; g_settings_error.clear(); g_rate_control = "CBR"; + g_encoder_active = false; + g_crf = -1; + g_use_bufsize = false; + g_update_calls = 0; g_encoder_id = "obs_x264"; g_encoder_caps = OBS_ENCODER_CAP_DYN_BITRATE; g_ladder = false; @@ -734,6 +753,51 @@ int main() } printf("video follows only a live-retunable encoder: ok\n"); + // An encoder already running (shared with a recording that started first) cannot switch + // rate control, so its settings are left as they are: a cap it runs with is advertised, + // and one it runs without refuses the output with a reason. + { + struct ActiveCase { + const char *id; + const char *rate_control; + long long crf; + bool use_bufsize; + bool active; + bool starts; + // Whether Start() rewrites the encoder's settings. + bool rewrites; + }; + for (const auto &c : + {// Not running yet: today's behavior, the buffer and the lossless CRF are replaced. + ActiveCase{"obs_x264", "VBR", 23, true, false, true, true}, + ActiveCase{"obs_x264", "VBR", 0, false, false, true, true}, + // Running with a cap: kept as it is, even with a buffer of its own. + ActiveCase{"obs_x264", "VBR", 23, true, true, true, false}, + ActiveCase{"obs_x264", "CBR", 0, false, true, true, false}, + ActiveCase{"obs_nvenc_h264_tex", "CQVBR", -1, false, true, true, false}, + // Running without one: refused. + ActiveCase{"obs_x264", "CQP", -1, false, true, false, false}, + ActiveCase{"obs_x264", "VBR", 0, false, true, false, false}, + ActiveCase{"obs_nvenc_h264_tex", "CQP", -1, false, true, false, false}}) { + TestRelay relay; + reset(relay.Url()); + g_encoder_id = c.id; + g_rate_control = c.rate_control; + g_crf = c.crf; + g_use_bufsize = c.use_bufsize; + g_encoder_active = c.active; + MoQOutput o(nullptr, OUTPUT); + CHECK(o.Start() == c.starts); + CHECK((g_update_calls > 0) == c.rewrites); + { + std::lock_guard lock(g_signals_mutex); + CHECK(g_last_error.empty() == c.starts); + } + o.Stop(); + } + } + printf("a running encoder keeps its settings and must hold a cap: ok\n"); + // Stopping hands the configured bitrate back to an encoder the grant lowered, // so the next Start() reads the user's rate rather than the last grant. { diff --git a/doc/bin/obs.md b/doc/bin/obs.md index 77d49de65b4..f9c807b063e 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -59,7 +59,13 @@ it holds whatever else the settings say: checked. The log names each setting of yours it replaced. An encoder shared with a -recording takes the cap too. The dock's Custom settings profiles start from +recording takes the cap too, unless the recording started first: a running +encoder cannot switch rate control, so its settings stay as they are and the +catalog advertises the cap it runs with. If it runs without one (constant +quality such as CQP or CRF, or lossless), the output refuses to start. Stop the +recording first, or give it its own encoder. + +The dock's Custom settings profiles start from constant quality under the cap on x264 and NVENC: Quality caps at 8 Mbps and Performance at 2.5 Mbps, which a complex scene reaches and a calm one stays well under. **Use OBS Output settings** starts from the rate control OBS configured. diff --git a/quest/m1/video-rate/obs.md b/quest/m1/video-rate/obs.md index 2d1a7609946..1b831be5fab 100644 --- a/quest/m1/video-rate/obs.md +++ b/quest/m1/video-rate/obs.md @@ -21,7 +21,9 @@ recommends the dock profiles), NVENC keeps CBR and VBR and otherwise runs `CQVBR` with `max_bitrate`, and every other encoder runs CBR at the cap. The output prices and retunes that peak (NVENC under `max_bitrate`). Quick Sync (ICQ has no max rate) and AMF (QVBR sets no -peak) stay CBR for good. +peak) stay CBR for good. An encoder already running when the output starts keeps its +settings and the catalog advertises the cap it runs with; one running uncapped (CQP, CRF, +lossless) refuses the output. Remaining, each needing hardware to measure that the peak holds: From 6f6dd40eb0b90568b6a84a0a79628e968753b902 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 17:01:21 -0800 Subject: [PATCH 10/11] fix(obs): a running x264 with a zero buffer is uncapped, and ABR holds its bitrate A custom x264 buffer of 0 makes x264 ignore the VBV in every mode, so a running encoder with one advertises no cap. ABR sits under the same VBV as VBR, and only VBR reads the CRF. NVENC's opts that set a rate are reported like x264opts. Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 58 ++++++++++++++++++-------- cpp/obs/src/moq-output.cpp | 12 +++--- cpp/obs/test/moq-encoder-rate-test.cpp | 42 +++++++++++++++---- cpp/obs/test/moq-output-test.cpp | 28 +++++++++---- doc/bin/obs.md | 7 +++- 5 files changed, 105 insertions(+), 42 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index 1672b28b4f4..87198ffedff 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -25,9 +25,10 @@ inline const char *EncoderPeakKey(const std::string &id, std::string rate_contro // CBR holds the encoder at its bitrate, so that is also its peak. if (rate_control == "CBR") return "bitrate"; - // x264's VBR is constant quality (CRF) under a VBV whose max rate is the bitrate. + // x264's VBR is constant quality (CRF) and its ABR an average, both under a VBV whose max + // rate is the bitrate. if (id == "obs_x264") - return rate_control == "VBR" ? "bitrate" : nullptr; + return rate_control == "VBR" || rate_control == "ABR" ? "bitrate" : nullptr; // NVENC's VBR averages at "bitrate" but never exceeds "max_bitrate"; CQVBR is // constant quality under that same max, and ignores "bitrate". if (id.rfind("obs_nvenc_", 0) == 0) @@ -81,27 +82,47 @@ inline long long ConfiguredCapKbps(const std::string &id, obs_data_t *settings) } // The hard peak in kbps an encoder already running with `settings` holds, or 0 when it runs -// uncapped: a quality mode with no peak (CQP, CRF, ICQ), or x264's lossless CRF of 0, which -// runs as constant QP with no VBV. The settings are read as they are, never rewritten. +// uncapped: a quality mode with no peak (CQP, CRF, ICQ), x264's lossless CRF of 0 (constant +// QP with no VBV), or x264 with a buffer of its own set to 0, which makes it ignore the VBV +// in every mode. The settings are read as they are, never rewritten. inline long long RunningCapKbps(const std::string &id, obs_data_t *settings) { const MoQPeak peak = EncoderPeak(id, settings); if (!peak.key) return 0; - if (id == "obs_x264" && Upper(obs_data_get_string(settings, "rate_control")) != "CBR" && - obs_data_get_int(settings, "crf") <= 0) - return 0; + if (id == "obs_x264") { + if (obs_data_get_bool(settings, "use_bufsize") && obs_data_get_int(settings, "buffer_size") <= 0) + return 0; + // Only VBR reads the CRF: ABR and CBR zero it. + if (Upper(obs_data_get_string(settings, "rate_control")) == "VBR" && + obs_data_get_int(settings, "crf") <= 0) + return 0; + } return peak.kbps; } -// The options in `x264opts` that set a rate of their own: OBS applies them after its rate -// parameters, so `vbv-maxrate` and `vbv-bufsize` replace the VBV (0 disables it), `bitrate` +// The setting that holds an encoder's free-form options, which OBS applies after its own +// rate settings, or null when it has none. +inline const char *EncoderOptionsKey(const std::string &id) +{ + if (id == "obs_x264") + return "x264opts"; + return IsNvenc(id) ? "opts" : nullptr; +} + +// The options the encoder's free-form options set a rate with, which replace the cap. +// For x264, `vbv-maxrate` and `vbv-bufsize` replace the VBV (0 disables it), `bitrate` // replaces the rate mode, and `qp` or a `crf` of 0 (lossless) drops the VBV for constant QP. -// The plugin never rewrites the text, so these can override the cap. -inline std::vector X264RateOptions(const std::string &options) +// For NVENC, `maxBitRate`, `averageBitRate`, and `vbvBufferSize` replace the rate it was +// given. The plugin never rewrites the text, so these can override the cap. +inline std::vector RateOptions(const std::string &id, obs_data_t *settings) { - std::istringstream input(options); + const char *key = EncoderOptionsKey(id); std::vector found; + if (!key) + return found; + const bool x264 = id == "obs_x264"; + std::istringstream input(obs_data_get_string(settings, key)); std::string option; while (input >> option) { std::string name = option.substr(0, option.find('=')); @@ -111,7 +132,9 @@ inline std::vector X264RateOptions(const std::string &options) const size_t assign = option.find('='); const bool lossless = name == "crf" && assign != std::string::npos && std::atof(option.c_str() + assign + 1) <= 0; - if (name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp" || lossless) + if (x264 ? name == "vbv-maxrate" || name == "vbv-bufsize" || name == "bitrate" || name == "qp" || + lossless + : name == "maxBitRate" || name == "averageBitRate" || name == "vbvBufferSize") found.push_back(option); } return found; @@ -123,7 +146,7 @@ struct MoQCap { bool changed = false; // The user's rate settings it replaced, each described for a log line. std::vector replaced; - // The `x264opts` options that can override the cap, which it leaves as the user wrote them. + // The free-form options that can override the cap, which it leaves as the user wrote them. std::vector overridden; }; @@ -131,8 +154,8 @@ struct MoQCap { // `write` (the same settings, to rewrite them in place). The cap is the plugin's: it // replaces any rate the user set that would exceed it, and says which in `replaced`. // - x264 keeps CBR and otherwise runs VBR (CRF under a VBV whose max rate and buffer are -// the bitrate). It writes only OBS's own settings: `x264opts` stays as the user wrote -// it, and the options in it that set a rate are reported in `overridden`. +// the bitrate). It writes only OBS's own settings: `x264opts` (and NVENC's `opts`) stay as +// the user wrote them, and the options in them that set a rate are reported in `overridden`. // - NVENC keeps CBR and VBR, with `max_bitrate` at the cap and the average under it, and // otherwise runs CQVBR (constant quality under `max_bitrate`). // - Everything else runs CBR at the cap: its quality modes carry no hard peak, or depend @@ -145,7 +168,6 @@ inline MoQCap EnforceCap(const std::string &id, obs_data_t *read, obs_data_t *wr const std::string before = obs_data_get_string(read, "rate_control"); const std::string mode = Upper(before); const long long average = obs_data_get_int(read, "bitrate"); - const std::string x264opts = obs_data_get_string(read, "x264opts"); const bool use_bufsize = obs_data_get_bool(read, "use_bufsize"); auto set_int = [&](const char *key, long long value) { @@ -178,7 +200,6 @@ inline MoQCap EnforceCap(const std::string &id, obs_data_t *read, obs_data_t *wr result.changed = true; result.replaced.push_back("use_bufsize"); } - result.overridden = X264RateOptions(x264opts); } else if (IsNvenc(id)) { set_mode(mode == "CBR" || mode == "VBR" ? mode.c_str() : "CQVBR"); // CBR's peak is its bitrate and constant quality ignores it; VBR averages under its peak. @@ -195,6 +216,7 @@ inline MoQCap EnforceCap(const std::string &id, obs_data_t *read, obs_data_t *wr set_mode("CBR"); set_int("bitrate", cap_kbps); } + result.overridden = RateOptions(id, read); return result; } diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 8182e88fc65..266b9f8a595 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -131,9 +131,9 @@ std::string CapEncoders(obs_output_t *output) " is already running without a bitrate cap (rate control " + obs_data_get_string(settings, "rate_control") + "). Stop the recording first, or give it its own encoder."; - for (const std::string &option : X264RateOptions(obs_data_get_string(settings, "x264opts"))) - LOG_WARNING("Video encoder %s: x264opts %s can override its %lld kbps cap", id, - option.c_str(), running); + for (const std::string &option : RateOptions(id, settings)) + LOG_WARNING("Video encoder %s: %s %s can override its %lld kbps cap", id, + EncoderOptionsKey(id), option.c_str(), running); LOG_INFO("Video encoder %s already running, advertising its %lld kbps cap", id, running); continue; } @@ -143,9 +143,9 @@ std::string CapEncoders(obs_output_t *output) LOG_WARNING("Video encoder %s: replacing %s to hold its %lld kbps cap", id, replaced.c_str(), cap); for (const std::string &option : result.overridden) - LOG_WARNING("Video encoder %s: x264opts %s can override the %lld kbps cap. Use the MoQ " - "dock's Quality or Performance profile, which hold it without x264opts.", - id, option.c_str(), cap); + LOG_WARNING("Video encoder %s: %s %s can override the %lld kbps cap. Use the MoQ " + "dock's Quality or Performance profile, which hold it without it.", + id, EncoderOptionsKey(id), option.c_str(), cap); if (result.changed) obs_encoder_update(encoder, patch); LOG_INFO("Video encoder %s capped at %lld kbps", id, cap); diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index b7c628d8faa..3ecbad9d294 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -53,27 +53,53 @@ int main() assert(rate_control(x264) == "VBR" && obs_data_get_int(&x264, "bitrate") == 8000); assert(EncoderPeak("obs_x264", &x264).kbps == 8000); - // A running encoder's cap is what its settings hold: its peak, or none for a quality mode - // and for x264's lossless CRF. + // A running encoder's cap is what its settings hold: its peak, or none for a quality mode, + // x264's lossless CRF, and x264's own buffer of 0 (which drops the VBV in every mode). struct Running { const char *id; const char *mode; long long crf; long long expect; + bool use_bufsize = false; + long long buffer_size = 0; }; - for (const Running &c : - {Running{"obs_x264", "CBR", 0, 6000}, Running{"obs_x264", "VBR", 23, 6000}, - Running{"obs_x264", "VBR", 0, 0}, Running{"obs_x264", "CRF", 23, 0}, Running{"obs_x264", "CQP", 23, 0}, - Running{"obs_nvenc_h264_tex", "CQP", 0, 0}, Running{"obs_nvenc_h264_tex", "CQVBR", 0, 7000}, - Running{"obs_qsv11_v2", "ICQ", 0, 0}}) { + for (const Running &c : {Running{"obs_x264", "CBR", 0, 6000}, + Running{"obs_x264", "VBR", 23, 6000}, + Running{"obs_x264", "VBR", 0, 0}, + Running{"obs_x264", "ABR", 0, 6000}, + Running{"obs_x264", "CRF", 23, 0}, + Running{"obs_x264", "CQP", 23, 0}, + Running{"obs_x264", "CBR", 0, 6000, true, 12000}, + Running{"obs_x264", "VBR", 23, 6000, true, 12000}, + Running{"obs_x264", "CBR", 0, 0, true, 0}, + Running{"obs_x264", "VBR", 23, 0, true, 0}, + Running{"obs_x264", "ABR", 0, 0, true, 0}, + Running{"obs_x264", "VBR", 23, 6000, false, 0}, + Running{"obs_nvenc_h264_tex", "CQP", 0, 0}, + Running{"obs_nvenc_h264_tex", "CQVBR", 0, 7000}, + Running{"obs_nvenc_h264_tex", "VBR", 0, 7000}, + Running{"obs_nvenc_h264_tex", "CBR", 0, 6000}, + Running{"obs_nvenc_h264_tex", "lossless", 0, 0}, + Running{"obs_qsv11_v2", "ICQ", 0, 0}, + Running{"obs_qsv11_v2", "VBR", 0, 0}, + Running{"obs_qsv11_v2", "CBR", 0, 6000}}) { obs_data_t running; obs_data_set_string(&running, "rate_control", c.mode); obs_data_set_int(&running, "bitrate", 6000); obs_data_set_int(&running, "max_bitrate", 7000); obs_data_set_int(&running, "crf", c.crf); + obs_data_set_bool(&running, "use_bufsize", c.use_bufsize); + obs_data_set_int(&running, "buffer_size", c.buffer_size); assert(RunningCapKbps(c.id, &running) == c.expect); } + // NVENC's opts can replace its rates, and are reported rather than rewritten. + obs_data_t nvenc_opts; + obs_data_set_string(&nvenc_opts, "opts", "maxBitRate=20000 lookaheadLevel=1 vbvBufferSize=0"); + assert((RateOptions("obs_nvenc_h264_tex", &nvenc_opts) == + std::vector{"maxBitRate=20000", "vbvBufferSize=0"})); + assert(RateOptions("obs_qsv11_v2", &nvenc_opts).empty()); + // x264 runs the user's CBR or VBR at the cap, and anything else as VBR. A buffer of // its own is replaced. x264opts is never rewritten: the options in it that set a rate // are reported as overriding the cap, and the rest are not. @@ -122,7 +148,7 @@ int main() EnforceCap("obs_x264", &cbr_crf, &cbr_crf_patch, 6000); assert(!cbr_crf_patch.values.count("crf")); assert(!cbr_crf_patch.values.count("x264opts")); - assert(X264RateOptions("crf=0.0 crf=18") == std::vector{"crf=0.0"}); + assert(RateOptions("obs_x264", &cbr_crf) == std::vector{"crf=0.0"}); // A compliant encoder is not touched. obs_data_t clean, nothing; diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index 20dde4bd96c..6a51a0e71f1 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -68,6 +68,7 @@ std::atomic g_encoder_active{false}; // The x264 CRF and "use_bufsize" the settings report; a negative CRF is the stub's default. std::atomic g_crf{-1}; std::atomic g_use_bufsize{false}; +std::atomic g_buffer_size{-1}; // How many times Start() or a retune rewrote an encoder's settings. std::atomic g_update_calls{0}; // A reason Configure reports itself, for a setting the config cannot express. @@ -222,6 +223,8 @@ long long obs_data_get_int(obs_data_t *settings, const char *key) { if (g_crf >= 0 && std::string(key) == "crf") return g_crf; + if (g_buffer_size >= 0 && std::string(key) == "buffer_size") + return g_buffer_size; if (settings == reinterpret_cast(LOW_ENCODER)) return 2000; return settings == reinterpret_cast(MID_ENCODER) ? 4000 : 8000; @@ -363,6 +366,7 @@ void reset(std::string url) g_encoder_active = false; g_crf = -1; g_use_bufsize = false; + g_buffer_size = -1; g_update_calls = 0; g_encoder_id = "obs_x264"; g_encoder_caps = OBS_ENCODER_CAP_DYN_BITRATE; @@ -762,6 +766,8 @@ int main() const char *rate_control; long long crf; bool use_bufsize; + // The custom buffer in kbit, or -1 for the stub's own. + long long buffer_size; bool active; bool starts; // Whether Start() rewrites the encoder's settings. @@ -769,22 +775,28 @@ int main() }; for (const auto &c : {// Not running yet: today's behavior, the buffer and the lossless CRF are replaced. - ActiveCase{"obs_x264", "VBR", 23, true, false, true, true}, - ActiveCase{"obs_x264", "VBR", 0, false, false, true, true}, + ActiveCase{"obs_x264", "VBR", 23, true, -1, false, true, true}, + ActiveCase{"obs_x264", "VBR", 0, false, -1, false, true, true}, + ActiveCase{"obs_x264", "CBR", 0, true, 0, false, true, true}, // Running with a cap: kept as it is, even with a buffer of its own. - ActiveCase{"obs_x264", "VBR", 23, true, true, true, false}, - ActiveCase{"obs_x264", "CBR", 0, false, true, true, false}, - ActiveCase{"obs_nvenc_h264_tex", "CQVBR", -1, false, true, true, false}, + ActiveCase{"obs_x264", "VBR", 23, true, -1, true, true, false}, + ActiveCase{"obs_x264", "ABR", 0, false, -1, true, true, false}, + ActiveCase{"obs_x264", "CBR", 0, false, -1, true, true, false}, + ActiveCase{"obs_nvenc_h264_tex", "CQVBR", -1, false, -1, true, true, false}, // Running without one: refused. - ActiveCase{"obs_x264", "CQP", -1, false, true, false, false}, - ActiveCase{"obs_x264", "VBR", 0, false, true, false, false}, - ActiveCase{"obs_nvenc_h264_tex", "CQP", -1, false, true, false, false}}) { + ActiveCase{"obs_x264", "CQP", -1, false, -1, true, false, false}, + ActiveCase{"obs_x264", "VBR", 0, false, -1, true, false, false}, + ActiveCase{"obs_x264", "VBR", 23, true, 0, true, false, false}, + ActiveCase{"obs_x264", "ABR", 0, true, 0, true, false, false}, + ActiveCase{"obs_x264", "CBR", 0, true, 0, true, false, false}, + ActiveCase{"obs_nvenc_h264_tex", "CQP", -1, false, -1, true, false, false}}) { TestRelay relay; reset(relay.Url()); g_encoder_id = c.id; g_rate_control = c.rate_control; g_crf = c.crf; g_use_bufsize = c.use_bufsize; + g_buffer_size = c.buffer_size; g_encoder_active = c.active; MoQOutput o(nullptr, OUTPUT); CHECK(o.Start() == c.starts); diff --git a/doc/bin/obs.md b/doc/bin/obs.md index f9c807b063e..c66899f29c5 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -53,7 +53,9 @@ it holds whatever else the settings say: cap: the log warns, and the dock's Quality and Performance profiles hold it without them. - NVENC keeps CBR and VBR, and otherwise runs constant quality (CQVBR), with - `max_bitrate` at the cap and VBR's average under it. + `max_bitrate` at the cap and VBR's average under it. Its `opts` are never + rewritten either, so `maxBitRate`, `averageBitRate`, or `vbvBufferSize` in them + can override the cap, and the log warns. - Every other encoder runs CBR at the cap: Quick Sync's ICQ and AMF's QVBR have no hard peak, and VA-API's and VideoToolbox's quality modes have not been checked. @@ -62,7 +64,8 @@ The log names each setting of yours it replaced. An encoder shared with a recording takes the cap too, unless the recording started first: a running encoder cannot switch rate control, so its settings stay as they are and the catalog advertises the cap it runs with. If it runs without one (constant -quality such as CQP or CRF, or lossless), the output refuses to start. Stop the +quality such as CQP or CRF, lossless, or x264 with a buffer size of your own set +to 0, which turns its VBV off), the output refuses to start. Stop the recording first, or give it its own encoder. The dock's Custom settings profiles start from From 3b4e464972b0fae1ab2b00b922822110c927f24a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 17:58:50 -0800 Subject: [PATCH 11/11] test(obs): x264's ABR has a peak, so the peak-key table says so Co-Authored-By: Claude Sonnet 5.5 --- cpp/obs/src/moq-encoder-rate.h | 4 ++-- cpp/obs/test/moq-encoder-rate-test.cpp | 6 +++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/cpp/obs/src/moq-encoder-rate.h b/cpp/obs/src/moq-encoder-rate.h index 87198ffedff..10870dc3f52 100644 --- a/cpp/obs/src/moq-encoder-rate.h +++ b/cpp/obs/src/moq-encoder-rate.h @@ -17,8 +17,8 @@ inline std::string Upper(std::string text) } // The setting that holds the hard peak an encoder honors under `rate_control`, or null -// when it has none (CQP, CRF, ICQ, or a mode that only averages). The peak is what -// reservations, the catalog, and dynamic bitrate price a rendition at. +// when it has none (CQP, CRF, ICQ, or an encoder whose peak is not modeled, like QSV and AMF). +// The peak is what reservations, the catalog, and dynamic bitrate price a rendition at. inline const char *EncoderPeakKey(const std::string &id, std::string rate_control) { rate_control = Upper(std::move(rate_control)); diff --git a/cpp/obs/test/moq-encoder-rate-test.cpp b/cpp/obs/test/moq-encoder-rate-test.cpp index 3ecbad9d294..1f053888123 100644 --- a/cpp/obs/test/moq-encoder-rate-test.cpp +++ b/cpp/obs/test/moq-encoder-rate-test.cpp @@ -227,7 +227,11 @@ int main() assert(std::string(EncoderPeakKey("obs_x264", "cbr")) == "bitrate"); assert(std::string(EncoderPeakKey("obs_nvenc_h264_tex", "vbr")) == "max_bitrate"); assert(std::string(EncoderPeakKey("obs_nvenc_h264_tex", "CBR")) == "bitrate"); - for (const char *mode : {"CRF", "ABR", "CQP", "ICQ", "QVBR", "lossless", ""}) { + // x264's ABR is VBV-capped at its bitrate, so it has a peak that other encoders' ABR does not. + assert(std::string(EncoderPeakKey("obs_x264", "ABR")) == "bitrate"); + assert(std::string(EncoderPeakKey("obs_x264", "VBR")) == "bitrate"); + assert(!EncoderPeakKey("obs_qsv11_v2", "ABR")); + for (const char *mode : {"CRF", "CQP", "ICQ", "QVBR", "lossless", ""}) { assert(!EncoderPeakKey("obs_x264", mode) && !EncoderPeakKey("obs_nvenc_h264_tex", mode)); } assert(!EncoderPeakKey("obs_qsv11_v2", "VBR"));