fix(writer): align auto bitrate with YouTube official recommended settings

Replace the simplistic pixels*4 formula with YouTube's official H.264
bitrate recommendations (support.google.com/youtube/answer/2853702).
Uses linear interpolation by pixel count between reference points
(720p, 1080p, 1440p, 4K), extrapolation above 4K, and 720p floor
for lower resolutions. HEVC targets ~60% of H.264 bitrate.

Also:
- Change default codec to H264 (better compatibility and performance)
- Change default bitRate to 0 (auto) so YouTube-based auto takes effect
- Remove unreachable null check on getFreeFrame() and document the
  non-null guarantee on its declaration

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: wysaid

examples/desktop/6-record_video_c.c

@@ -126,12 +126,12 @@ int main(int argc, char** argv) {
     // Configure and open video writer
     CcapWriterConfig writerConfig;
     memset(&writerConfig, 0, sizeof(writerConfig));
-    writerConfig.codec = CCAP_VIDEO_CODEC_HEVC;
+    writerConfig.codec = CCAP_VIDEO_CODEC_H264;
     writerConfig.container = CCAP_VIDEO_FORMAT_MP4;
     writerConfig.width = (uint32_t)realWidth;
     writerConfig.height = (uint32_t)realHeight;
     writerConfig.frameRate = realFps > 0.0 ? realFps : 30.0;
-    writerConfig.bitRate = 5000000;
+    writerConfig.bitRate = 0;  // auto bit rate based on resolution and codec (YouTube recommended)
 
     CcapVideoWriter* writer = ccap_video_writer_create();
     if (!writer) {

include/ccap_writer.h

@@ -27,8 +27,8 @@ namespace ccap {
  * @brief Video codec for encoding.
  */
 enum class VideoCodec {
-    HEVC,  ///< H.265 / HEVC (preferred, better compression)
-    H264,  ///< H.264 / AVC (fallback, wider compatibility)
+    H264,  ///< H.264 / AVC (default, best compatibility and performance)
+    HEVC,  ///< H.265 / HEVC (better compression, less compatible)
 };
 
 /**
@@ -43,12 +43,12 @@ enum class VideoFormat {
  * @brief Configuration for video writer.
  */
 struct WriterConfig {
-    VideoCodec codec = VideoCodec::HEVC; ///< Preferred codec; auto-fallback to H.264 if unavailable
+    VideoCodec codec = VideoCodec::H264; ///< Default codec; auto-fallback to HEVC if H.264 is unavailable
     VideoFormat container = VideoFormat::MP4;
     uint32_t width = 0;          ///< Frame width in pixels
     uint32_t height = 0;         ///< Frame height in pixels
     double frameRate = 30.0;     ///< Target frame rate (default 30fps; used for timestamp generation when timestampNs is 0)
-    uint64_t bitRate = 5'000'000; ///< Target bit rate in bits/s; 0 = auto
+    uint64_t bitRate = 0;        ///< Target bit rate in bits/s; 0 = auto (YouTube official recommended bitrates)
 };
 
 /**

include/ccap_writer_c.h

@@ -27,8 +27,8 @@ typedef struct CcapVideoWriter CcapVideoWriter;
 
 /** @brief Video codec enumeration */
 typedef enum {
-    CCAP_VIDEO_CODEC_HEVC = 0,  ///< H.265 / HEVC (preferred)
-    CCAP_VIDEO_CODEC_H264 = 1,  ///< H.264 / AVC (fallback)
+    CCAP_VIDEO_CODEC_H264 = 0,  ///< H.264 / AVC (default, best compatibility)
+    CCAP_VIDEO_CODEC_HEVC = 1,  ///< H.265 / HEVC (better compression, less compatible)
 } CcapVideoCodec;
 
 /** @brief Video container format */
@@ -50,14 +50,14 @@ typedef struct {
     uint32_t width;                ///< Frame width
     uint32_t height;               ///< Frame height
     double frameRate;              ///< Target frame rate; 0 lets open() normalize to 30fps
-    uint64_t bitRate;              ///< Target bit rate in bits/s (0 = auto)
+    uint64_t bitRate;              ///< Target bit rate in bits/s (0 = auto, YouTube recommended bitrates)
 } CcapWriterConfig;
 
 /**
  * @brief Default initializer for `CcapWriterConfig`.
  * @note `width` and `height` remain 0 and must be assigned by the caller.
  */
-#define CCAP_WRITER_CONFIG_INIT { CCAP_VIDEO_CODEC_HEVC, CCAP_VIDEO_FORMAT_MP4, 0u, 0u, 30.0, 5000000ULL }
+#define CCAP_WRITER_CONFIG_INIT { CCAP_VIDEO_CODEC_H264, CCAP_VIDEO_FORMAT_MP4, 0u, 0u, 30.0, 0ULL }
 
 /* ========== Writer Lifecycle ========== */
 

src/ccap_writer_apple.mm

@@ -75,7 +75,7 @@ bool open(std::string_view filePath, const WriterConfig& config) override {
     bool tryOpen(AVFileType fileType, NSString* pathStr, AVVideoCodecType codec) {
         NSURL* url = [NSURL fileURLWithPath: pathStr];
         NSError* error = nil;
-        int64_t bitRate = (m_config.bitRate > 0) ? static_cast<int64_t>(m_config.bitRate) : static_cast<int64_t>(m_config.width) * m_config.height * 4;
+        int64_t bitRate = static_cast<int64_t>(effectiveBitRate(m_config));
         int frameRateInt = (m_config.frameRate > 0) ? static_cast<int>(m_config.frameRate) : 30;
         int maxKeyFrameInterval = frameRateInt * 2;
 

src/ccap_writer_imp.h

@@ -37,6 +37,91 @@ struct VideoWriter::Impl {
 /// Returns nullptr on unsupported platforms.
 VideoWriter::Impl* createVideoWriterImpl();
 
+/// Compute auto bit rate based on resolution and frame rate.
+///
+/// Reference: YouTube official recommended bitrates for H.264 encoding.
+/// https://support.google.com/youtube/answer/2853702
+///
+/// YouTube H.264 reference points (Mbps):
+///   720p  @30fps → 7.5    720p  @60fps → 9.0
+///   1080p @30fps → 10     1080p @60fps → 12
+///   1440p @30fps → 15     1440p @60fps → 24
+///   2160p @30fps → 30     2160p @60fps → 35
+///
+/// For resolutions below 720p, the 720p rate is used as floor.
+/// For resolutions between reference points, bit rate is linearly interpolated by pixel count.
+/// For resolutions above 4K, bit rate is extrapolated by pixel count.
+/// For HEVC, bit rate is scaled down to ~60% of H.264 (HEVC achieves similar quality at lower bit rate).
+inline uint64_t computeAutoBitRate(uint32_t width, uint32_t height, double frameRate, VideoCodec codec) {
+    const double kMbps = 1'000'000.0;
+    const double fps = (frameRate > 0.0) ? frameRate : 30.0;
+    const bool is60fps = fps > 45.0;
+
+    // YouTube H.264 reference data points: (pixelCount, bitrateInMbps)
+    struct RefPoint { double pixels; double bitrateMbps; };
+    static const RefPoint refs30[] = {
+        {1280 * 720,  7.5},
+        {1920 * 1080, 10.0},
+        {2560 * 1440, 15.0},
+        {3840 * 2160, 30.0},
+    };
+    static const RefPoint refs60[] = {
+        {1280 * 720,  9.0},
+        {1920 * 1080, 12.0},
+        {2560 * 1440, 24.0},
+        {3840 * 2160, 35.0},
+    };
+
+    const RefPoint* refs = is60fps ? refs60 : refs30;
+    const int refCount = 4;
+    const double pixels = static_cast<double>(width) * height;
+    double bitrateMbps;
+
+    if (pixels <= refs[0].pixels) {
+        // Below 720p: use 720p floor
+        bitrateMbps = refs[0].bitrateMbps;
+    } else if (pixels >= refs[refCount - 1].pixels) {
+        // Above 4K: extrapolate using slope of the last two reference points
+        const auto& a = refs[refCount - 2];
+        const auto& b = refs[refCount - 1];
+        double slope = (b.bitrateMbps - a.bitrateMbps) / (b.pixels - a.pixels);
+        bitrateMbps = b.bitrateMbps + slope * (pixels - b.pixels);
+    } else {
+        // Between reference points: linear interpolation by pixel count
+        int i = 0;
+        while (i < refCount - 1 && pixels > refs[i + 1].pixels) i++;
+        const auto& lo = refs[i];
+        const auto& hi = refs[i + 1];
+        double t = (pixels - lo.pixels) / (hi.pixels - lo.pixels);
+        bitrateMbps = lo.bitrateMbps + t * (hi.bitrateMbps - lo.bitrateMbps);
+    }
+
+    // Scale for non-standard frame rates between 30 and 60
+    if (!is60fps && fps > 30.0) {
+        const auto& r30 = refs30;
+        const auto& r60 = refs60;
+        // Average ratio across reference points
+        double ratio = 0;
+        for (int i = 0; i < refCount; i++) ratio += r60[i].bitrateMbps / r30[i].bitrateMbps;
+        ratio /= refCount; // ~1.27
+        double t = (fps - 30.0) / 30.0;
+        bitrateMbps *= (1.0 + t * (ratio - 1.0));
+    }
+
+    // HEVC achieves similar visual quality at ~60% of H.264 bit rate
+    if (codec == VideoCodec::HEVC) {
+        bitrateMbps *= 0.6;
+    }
+
+    return static_cast<uint64_t>(bitrateMbps * kMbps);
+}
+
+/// Resolve effective bit rate: use user value if set, otherwise compute auto.
+inline uint64_t effectiveBitRate(const WriterConfig& config) {
+    if (config.bitRate > 0) return config.bitRate;
+    return computeAutoBitRate(config.width, config.height, config.frameRate, config.codec);
+}
+
 // ---- Shared NV12 conversion helpers (used by both platform implementations) ----
 
 inline int orientedRowIndex(FrameOrientation orientation, int row, int height) {

src/ccap_writer_windows.cpp

@@ -255,7 +255,7 @@ class WriterWindows : public VideoWriter::Impl {
 
         pOutputType->SetGUID(MF_MT_MAJOR_TYPE, MFMediaType_Video);
         pOutputType->SetGUID(MF_MT_SUBTYPE, videoCodec);
-        pOutputType->SetUINT32(MF_MT_AVG_BITRATE, static_cast<UINT32>(config.bitRate > 0 ? config.bitRate : config.width * config.height * 4));
+        pOutputType->SetUINT32(MF_MT_AVG_BITRATE, static_cast<UINT32>(effectiveBitRate(config)));
         pOutputType->SetUINT32(MF_MT_INTERLACE_MODE, MFVideoInterlace_Progressive);
         MFSetAttributeSize(pOutputType, MF_MT_FRAME_SIZE, config.width, config.height);