fix: finalize writer PR hardening and docs alignment

Author: wysaid

BUILD_AND_INSTALL.md

@@ -55,6 +55,7 @@ make install
 - `CCAP_BUILD_EXAMPLES`: Build example applications (default: ON for root project)
 - `CCAP_BUILD_TESTS`: Build unit tests (default: OFF)
 - `CCAP_NO_LOG`: Disable logging functionality (default: OFF)
+- `CCAP_ENABLE_VIDEO_WRITER`: Enable video writer support (`ccap::VideoWriter`, C writer API, CLI `--record`) on Windows/macOS (default: ON)
 
 ### macOS Universal Binary Build
 
@@ -205,6 +206,7 @@ build/universal/          # Contains x86_64 + arm64 universal binary
 - `CCAP_INSTALL`: Enable install target (default: ON)
 - `CCAP_BUILD_EXAMPLES`: Build examples (default: OFF when used as subproject)
 - `CCAP_BUILD_TESTS`: Build tests (default: OFF when used as subproject)
+- `CCAP_ENABLE_VIDEO_WRITER`: Enable video writing support (Windows/macOS only, default: ON)
 
 ### Advanced Usage
 
@@ -250,6 +252,15 @@ git clean -fdx install/
 
 **Note**: Video file playback is currently supported on Windows and macOS only. Linux video playback support may be added in a future release.
 
+### Video Writer Support Matrix
+
+- ✅ Windows: supported (`CCAP_ENABLE_VIDEO_WRITER=ON`)
+- ✅ macOS: supported (`CCAP_ENABLE_VIDEO_WRITER=ON`)
+- ❌ Linux: not supported
+- ❌ iOS: not supported
+
+`CCAP_ENABLE_VIDEO_WRITER` is independent from `CCAP_ENABLE_FILE_PLAYBACK`.
+
 ## Version Information
 
 Current version: 1.7.2

README.md

@@ -38,6 +38,7 @@ A high-performance, lightweight cross-platform camera capture library with hardw
 - **Multiple Formats**: RGB, BGR, YUV (NV12/I420) with automatic conversion
 - **Dual Language APIs**: ✨ **Complete Pure C Interface** - Both modern C++ API and traditional C99 interface for various project integration and language bindings
 - **Video File Playback**: 🎬 Play video files (MP4, AVI, MOV, etc.) using the same API as camera capture - supports Windows and macOS
+- **Video Writing / Recording**: 🎥 Write MP4/MOV files from camera frames via `ccap::VideoWriter`, `ccap_video_writer_*`, or CLI `--record` (Windows/macOS, `CCAP_ENABLE_VIDEO_WRITER=ON`)
 - **CLI Tool**: Ready-to-use command-line tool for quick camera operations and video processing - list devices, capture images, real-time preview, video playback ([Documentation](./docs/content/cli.md))
 - **Production Ready**: Comprehensive test suite with 95%+ accuracy validation
 - **Virtual Camera Support**: Compatible with OBS Virtual Camera and similar tools through the default DirectShow path on Windows
@@ -235,6 +236,8 @@ On Windows, camera capture now uses DirectShow by default. This keeps OBS Virtua
 
 For most Windows applications, staying in `auto` mode is recommended. ccap normalizes the public capture API, frame orientation handling, and output pixel-format conversion across both backends so callers usually do not need backend-specific code.
 
+For video writing, backend selection is a separate axis: on Windows, `VideoWriter` uses Media Foundation's writer stack regardless of camera capture backend (`auto` / `dshow` / `msmf`).
+
 - Pass `extraInfo` as `"auto"`, `"msmf"`, `"dshow"`, or `"backend=<value>"` in the C++/C constructors that accept it.
 - Set the environment variable `CCAP_WINDOWS_BACKEND=auto|msmf|dshow` to affect the whole process, including the CLI and Rust bindings.
 
@@ -297,6 +300,9 @@ cmake --build .
 
 # Video preview with playback controls
 ./ccap -i video.mp4 --preview --speed 1.0
+
+# Record camera stream to MP4 (Windows/macOS)
+./ccap -d 0 --record ./camera_capture.mp4 --timeout 5
 ```
 
 **Key Features:**
@@ -305,6 +311,7 @@ cmake --build .
 - 🎯 Capture single or multiple images
 - 👁️ Real-time preview window (with GLFW)
 - 🎬 Video file playback and frame extraction
+- 🎥 Record camera stream to MP4/MOV (`--record`)
 - ⚙️ Configure resolution, format, and frame rate
 - 💾 Save images in various formats (JPEG, PNG, BMP, etc.)
 - ⏱️ Duration-based or count-based capture modes
@@ -343,6 +350,7 @@ For complete CLI documentation, see [CLI Tool Guide](./docs/content/cli.md).
 | [3-capture_callback](./examples/desktop/3-capture_callback.cpp) / [3-capture_callback_c](./examples/desktop/3-capture_callback_c.c) | Callback-based capture | C++ / C | Desktop |
 | [4-example_with_glfw](./examples/desktop/4-example_with_glfw.cpp) / [4-example_with_glfw_c](./examples/desktop/4-example_with_glfw_c.c) | OpenGL rendering | C++ / C | Desktop |
 | [5-play_video](./examples/desktop/5-play_video.cpp) / [5-play_video_c](./examples/desktop/5-play_video_c.c) | Video file playback | C++ / C | Windows/macOS |
+| [6-record_video](./examples/desktop/6-record_video.cpp) | Video recording with `VideoWriter` | C++ | Windows/macOS |
 | [iOS Demo](./examples/) | iOS application | Objective-C++ | iOS |
 
 ### Build and Run Examples
@@ -460,6 +468,41 @@ enum class PixelFormat : uint32_t {
 };
 ```
 
+### Video Writing (Windows/macOS)
+
+Video writing is available on Windows and macOS when `CCAP_ENABLE_VIDEO_WRITER=ON`.
+
+```cpp
+#include <ccap.h>
+#include <ccap_writer.h>
+
+ccap::Provider provider;
+ccap::VideoWriter writer;
+
+if (provider.open("", true)) {
+    ccap::WriterConfig cfg;
+    cfg.width = 1280;
+    cfg.height = 720;
+    cfg.frameRate = 30.0;
+    cfg.codec = ccap::VideoCodec::H264;
+    cfg.container = ccap::VideoFormat::MP4;
+
+    if (writer.open("camera_record.mp4", cfg)) {
+        while (auto frame = provider.grab(3000)) {
+            // timestampNs == 0 means auto timestamp generation from frameRate.
+            writer.writeFrame(*frame, 0);
+        }
+        writer.close();
+    }
+}
+```
+
+Notes:
+
+- Writer input supports `NV12`, `I420`, `BGR24`, and `BGRA32`.
+- `VideoFrame::orientation` is honored by the writer path (including `BottomToTop` frames common on Windows RGB capture).
+- `CCAP_ENABLE_VIDEO_WRITER` is independent from `CCAP_ENABLE_FILE_PLAYBACK`.
+
 ### Utility Functions
 
 ```cpp
@@ -575,6 +618,20 @@ void ccap_provider_stop(CcapProvider* provider);
 bool ccap_provider_is_started(CcapProvider* provider);
 ```
 
+##### Video Writer API (C)
+
+```c
+CcapVideoWriter* ccap_video_writer_create(void);
+void ccap_video_writer_destroy(CcapVideoWriter* writer);
+bool ccap_video_writer_open(CcapVideoWriter* writer, const char* filePath, const CcapWriterConfig* config);
+bool ccap_video_writer_write_frame(CcapVideoWriter* writer, const CcapVideoFrameInfo* frameInfo, uint64_t timestampNs);
+void ccap_video_writer_close(CcapVideoWriter* writer);
+bool ccap_video_writer_is_opened(const CcapVideoWriter* writer);
+CcapVideoCodec ccap_video_writer_actual_codec(const CcapVideoWriter* writer);
+```
+
+`timestampNs == 0` is treated as an auto-timestamp sentinel (derived from configured frame rate), not a literal timeline timestamp.
+
 ##### Frame Capture and Processing
 
 ```c
@@ -729,6 +786,7 @@ Comprehensive test suite with 50+ test cases covering all functionality:
 - Multi-backend testing (CPU, AVX2, Apple Accelerate, NEON)
 - Performance benchmarks and accuracy validation  
 - 95%+ precision for pixel format conversions
+- Video writer regression tests (`ccap_video_writer_test`) covering C++ and C APIs, codec fallback, MOV container, `BottomToTop` orientation, and transcode duration checks
 
 ```bash
 ./scripts/run_tests.sh

README.zh-CN.md

@@ -38,6 +38,7 @@
 - **多种格式**：RGB、BGR、YUV（NV12/I420）及自动转换
 - **双语言接口**：✨ **新增完整纯 C 接口**，同时提供现代化 C++ API 和传统 C99 接口，支持各种项目集成和语言绑定
 - **视频文件播放**：🎬 使用与相机相同的 API 播放视频文件（MP4、AVI、MOV 等）- 支持 Windows 和 macOS
+- **视频写入 / 录制**：🎥 通过 `ccap::VideoWriter`、`ccap_video_writer_*` 或 CLI `--record` 将相机帧写入 MP4/MOV（Windows/macOS，需 `CCAP_ENABLE_VIDEO_WRITER=ON`）
 - **命令行工具**：开箱即用的命令行工具，快速实现相机操作和视频处理 - 列出设备、捕获图像、实时预览、视频播放（[文档](./docs/content/cli.zh.md)）
 - **生产就绪**：完整测试套件，95%+ 精度验证
 - **虚拟相机支持**：在 Windows 上通过默认 DirectShow 路径兼容 OBS Virtual Camera 等工具
@@ -198,6 +199,8 @@ Windows 上现在默认使用 DirectShow。这样做的主要原因是 DirectSho
 
 对大多数 Windows 应用来说，建议直接使用 `auto` 模式。ccap 会在两个后端之上统一公开的采集 API、帧朝向处理和输出像素格式转换，所以调用方通常不需要编写后端分支逻辑。
 
+对于视频写入，后端选择是另一条独立维度：在 Windows 上，`VideoWriter` 固定使用 Media Foundation 写入链路，不受相机采集后端（`auto` / `dshow` / `msmf`）切换影响。
+
 - 在支持 `extraInfo` 的 C++ / C 构造接口中传入 `"auto"`、`"msmf"`、`"dshow"` 或 `"backend=<value>"`。
 - 设置环境变量 `CCAP_WINDOWS_BACKEND=auto|msmf|dshow`，对整个进程生效，包括 CLI 和 Rust 绑定。
 
@@ -266,13 +269,17 @@ cmake --build .
 
 # 视频预览并控制播放
 ./ccap -i video.mp4 --preview --speed 1.0
+
+# 将相机流录制为 MP4（Windows/macOS）
+./ccap -d 0 --record ./camera_capture.mp4 --timeout 5
 ```
 
 **主要功能：**
 - 📷 列出和选择相机设备
 - 🎯 捕获单张或多张图像
 - 👁️ 实时预览窗口（需要 GLFW）
 - 🎬 视频文件播放和帧提取
+- 🎥 将相机流录制为 MP4/MOV（`--record`）
 - ⚙️ 配置分辨率、格式和帧率
 - 💾 保存为多种图像格式（JPEG、PNG、BMP 等）
 - ⏱️ 基于时长或数量的捕获模式
@@ -310,6 +317,7 @@ cmake --build .
 | [3-capture_callback](./examples/desktop/3-capture_callback.cpp) / [3-capture_callback_c](./examples/desktop/3-capture_callback_c.c) | 回调式捕获 | C++ / C | 桌面端 |
 | [4-example_with_glfw](./examples/desktop/4-example_with_glfw.cpp) / [4-example_with_glfw_c](./examples/desktop/4-example_with_glfw_c.c) | OpenGL 渲染 | C++ / C | 桌面端 |
 | [5-play_video](./examples/desktop/5-play_video.cpp) / [5-play_video_c](./examples/desktop/5-play_video_c.c) | 视频文件播放 | C++ / C | Windows/macOS |
+| [6-record_video](./examples/desktop/6-record_video.cpp) | 使用 `VideoWriter` 录制视频 | C++ | Windows/macOS |
 | [iOS Demo](./examples/) | iOS 应用程序 | Objective-C++ | iOS |
 
 ### 构建和运行示例
@@ -429,6 +437,41 @@ enum class PixelFormat : uint32_t {
 };
 ```
 
+### 视频写入（Windows/macOS）
+
+当 `CCAP_ENABLE_VIDEO_WRITER=ON` 时，可在 Windows/macOS 使用视频写入能力。
+
+```cpp
+#include <ccap.h>
+#include <ccap_writer.h>
+
+ccap::Provider provider;
+ccap::VideoWriter writer;
+
+if (provider.open("", true)) {
+    ccap::WriterConfig cfg;
+    cfg.width = 1280;
+    cfg.height = 720;
+    cfg.frameRate = 30.0;
+    cfg.codec = ccap::VideoCodec::H264;
+    cfg.container = ccap::VideoFormat::MP4;
+
+    if (writer.open("camera_record.mp4", cfg)) {
+        while (auto frame = provider.grab(3000)) {
+            // timestampNs == 0 表示根据 frameRate 自动生成时间戳。
+            writer.writeFrame(*frame, 0);
+        }
+        writer.close();
+    }
+}
+```
+
+说明：
+
+- 写入输入像素格式支持 `NV12`、`I420`、`BGR24`、`BGRA32`。
+- 写入链路会尊重 `VideoFrame::orientation`（包括 Windows RGB 常见的 `BottomToTop`）。
+- `CCAP_ENABLE_VIDEO_WRITER` 与 `CCAP_ENABLE_FILE_PLAYBACK` 为独立开关。
+
 ### 工具函数
 
 ```cpp
@@ -544,6 +587,20 @@ void ccap_provider_stop(CcapProvider* provider);
 bool ccap_provider_is_started(CcapProvider* provider);
 ```
 
+##### 视频写入 API（C）
+
+```c
+CcapVideoWriter* ccap_video_writer_create(void);
+void ccap_video_writer_destroy(CcapVideoWriter* writer);
+bool ccap_video_writer_open(CcapVideoWriter* writer, const char* filePath, const CcapWriterConfig* config);
+bool ccap_video_writer_write_frame(CcapVideoWriter* writer, const CcapVideoFrameInfo* frameInfo, uint64_t timestampNs);
+void ccap_video_writer_close(CcapVideoWriter* writer);
+bool ccap_video_writer_is_opened(const CcapVideoWriter* writer);
+CcapVideoCodec ccap_video_writer_actual_codec(const CcapVideoWriter* writer);
+```
+
+`timestampNs == 0` 会被视为“自动时间戳哨兵值”（按配置帧率推导），而不是一个字面上的时间轴时间戳。
+
 ##### 帧捕获和处理
 
 ```c
@@ -650,6 +707,7 @@ C 接口的详细使用说明和示例请参见：[C 接口文档](./docs/conten
 - 多后端测试（CPU、AVX2、Apple Accelerate、NEON）
 - 性能基准测试和精度验证
 - 像素格式转换 95%+ 精度
+- 视频写入回归测试（`ccap_video_writer_test`），覆盖 C++/C API、codec 回退、MOV 容器、`BottomToTop` 方向与转码时长校验
 
 ```bash
 ./scripts/run_tests.sh

cli/args_parser.cpp

@@ -352,6 +352,10 @@ CLIOptions parseArgs(int argc, char* argv[]) {
             opts.showVersion = true;
         } else if (arg == "--verbose") {
             opts.verbose = true;
+            opts.quiet = false;
+        } else if (arg == "-q" || arg == "--quiet") {
+            opts.quiet = true;
+            opts.verbose = false;
         } else if (arg == "--json") {
             opts.jsonOutput = true;
         } else if (arg == "--schema-version") {

cli/args_parser.h

@@ -34,6 +34,7 @@ struct CLIOptions {
     bool listDevices = false;
     bool showDeviceInfo = false;
     bool verbose = false;
+    bool quiet = false;
     bool jsonOutput = false;
     std::string schemaVersion = "1.0";
 

cli/ccap_cli.cpp

@@ -91,22 +91,10 @@ int main(int argc, char* argv[]) {
     // Set log level based on options
     if (opts.verbose) {
         ccap::setLogLevel(ccap::LogLevel::Verbose);
+    } else if (opts.quiet) {
+        ccap::setLogLevel(ccap::LogLevel::Error);
     } else {
-        // Check if -q/--quiet was specified by looking at argv
-        bool quietMode = false;
-        for (int i = 1; i < argc; ++i) {
-            std::string arg = argv[i];
-            if (arg == "-q" || arg == "--quiet") {
-                quietMode = true;
-                break;
-            }
-        }
-        
-        if (quietMode) {
-            ccap::setLogLevel(ccap::LogLevel::Error);
-        } else {
-            ccap::setLogLevel(ccap::LogLevel::Info);
-        }
+        ccap::setLogLevel(ccap::LogLevel::Info);
     }
 
     // Set error callback