feat: add video file writing support for macOS and Windows

CMakeLists.txt

@@ -132,8 +132,27 @@ if (NOT CCAP_ENABLE_FILE_PLAYBACK)
     message(STATUS "ccap: Video file playback support disabled")
 endif ()
 
+# Video writer sources (Windows and macOS only)
+option(CCAP_ENABLE_VIDEO_WRITER "Enable video file writing support (Windows/macOS)" ON)
+if (CCAP_ENABLE_VIDEO_WRITER AND (APPLE OR WIN32))
+    # Exclude writer sources from main glob to avoid double-compilation (platform impl included via #include)
+    list(FILTER LIB_SOURCE EXCLUDE REGEX ".*ccap_writer_apple.*")
+    list(FILTER LIB_SOURCE EXCLUDE REGEX ".*ccap_writer_windows.*")
+    list(FILTER LIB_SOURCE EXCLUDE REGEX ".*ccap_writer_c\..*$")
+    list(FILTER LIB_SOURCE EXCLUDE REGEX ".*ccap_writer\..*$")
+    list(APPEND LIB_SOURCE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/ccap_writer.mm
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/ccap_writer_c.cpp
+    )
+    message(STATUS "ccap: Video file writing support enabled")
+else ()
+    message(STATUS "ccap: Video file writing support disabled (unsupported platform or disabled)")
+endif ()
+
 if (APPLE)
     file(GLOB LIB_SOURCE_MAC ${CMAKE_CURRENT_SOURCE_DIR}/src/*.mm)
+    list(FILTER LIB_SOURCE_MAC EXCLUDE REGEX ".*ccap_writer_apple.*")
+    list(FILTER LIB_SOURCE_MAC EXCLUDE REGEX ".*ccap_writer\.mm$")
     message(STATUS "ccap: Using Objective-C++ for macOS: ${LIB_SOURCE_MAC}")
     list(APPEND LIB_SOURCE ${LIB_SOURCE_MAC})
 endif ()
@@ -207,6 +226,10 @@ else ()
     message(STATUS "ccap: Video file playback support disabled")
 endif ()
 
+if (CCAP_ENABLE_VIDEO_WRITER AND (APPLE OR WIN32))
+    target_compile_definitions(ccap PUBLIC CCAP_ENABLE_VIDEO_WRITER=1)
+endif ()
+
 # Configure shared library export definitions
 if (CCAP_BUILD_SHARED)
     target_compile_definitions(ccap PUBLIC CCAP_SHARED=1)

include/ccap_c.h

@@ -93,6 +93,12 @@ typedef enum {
     CCAP_ERROR_FILE_OPEN_FAILED = 0x5001,      /**< Failed to open video file */
     CCAP_ERROR_UNSUPPORTED_VIDEO_FORMAT = 0x5002, /**< Video format is not supported */
     CCAP_ERROR_SEEK_FAILED = 0x5003,           /**< Seek operation failed */
+    /* Video writer error codes */
+    CCAP_ERROR_WRITER_OPEN_FAILED = 0x6001,    /**< Failed to open video writer */
+    CCAP_ERROR_WRITER_WRITE_FAILED = 0x6002,   /**< Failed to write frame */
+    CCAP_ERROR_WRITER_CLOSE_FAILED = 0x6003,   /**< Failed to finalize file */
+    CCAP_ERROR_WRITER_NOT_OPENED = 0x6004,     /**< Writer not opened */
+    CCAP_ERROR_UNSUPPORTED_CODEC = 0x6005,     /**< Codec not supported on this platform */
     CCAP_ERROR_INTERNAL_ERROR = 0x9999,        /**< Unknown or internal error */
 } CcapErrorCode;
 

include/ccap_def.h

@@ -309,6 +309,23 @@ enum class ErrorCode {
     /// Seek operation failed
     SeekFailed = 0x5003,
 
+    // ============== Video Writer Errors ==============
+
+    /// Failed to open video writer
+    WriterOpenFailed = 0x6001,
+
+    /// Failed to write frame
+    WriterWriteFailed = 0x6002,
+
+    /// Failed to finalize file
+    WriterCloseFailed = 0x6003,
+
+    /// Writer not opened
+    WriterNotOpened = 0x6004,
+
+    /// Codec not supported on this platform
+    UnsupportedCodec = 0x6005,
+
     /// Unknown or internal error
     InternalError = 0x9999,
 };

include/ccap_writer.h

@@ -0,0 +1,104 @@
+/**
+ * @file ccap_writer.h
+ * @author wysaid (this@wysaid.org)
+ * @brief Video writer header file for ccap.
+ * @date 2025-05
+ *
+ * @note Requires CCAP_ENABLE_VIDEO_WRITER to be defined.
+ *       Only available on Windows and macOS.
+ */
+
+#ifndef __cplusplus
+#error "ccap_writer.h is for C++ only. For C language, please use ccap_writer_c.h instead."
+#endif
+
+#pragma once
+#ifndef CCAP_WRITER_H
+#define CCAP_WRITER_H
+
+#include "ccap_def.h"
+
+#include <memory>
+#include <string_view>
+
+namespace ccap {
+
+/**
+ * @brief Video codec for encoding.
+ */
+enum class VideoCodec {
+    HEVC,  ///< H.265 / HEVC (preferred, better compression)
+    H264,  ///< H.264 / AVC (fallback, wider compatibility)
+};
+
+/**
+ * @brief Video container format.
+ */
+enum class VideoFormat {
+    MP4,   ///< MP4 container
+    MOV,   ///< MOV container
+};
+
+/**
+ * @brief Configuration for video writer.
+ */
+struct WriterConfig {
+    VideoCodec codec = VideoCodec::HEVC; ///< Preferred codec; auto-fallback to H.264 if 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; 0 = variable rate
+    uint64_t bitRate = 5'000'000; ///< Target bit rate in bits/s; 0 = auto
+};
+
+/**
+ * @brief Video file writer. Captures frames and encodes them into a video file.
+ * @note This class is not thread-safe. Use it in a single thread or protect with a mutex.
+ */
+class CCAP_EXPORT VideoWriter {
+public:
+    VideoWriter();
+    ~VideoWriter();
+
+    /// Move-only
+    VideoWriter(VideoWriter&&) noexcept;
+    VideoWriter& operator=(VideoWriter&&) noexcept;
+    VideoWriter(const VideoWriter&) = delete;
+    VideoWriter& operator=(const VideoWriter&) = delete;
+
+    /**
+     * @brief Open writer to a file path.
+     * @param filePath Output file path (e.g., "output.mp4")
+     * @param config Writer configuration (width, height, codec, etc.)
+     * @return true on success, false on failure.
+     */
+    bool open(std::string_view filePath, const WriterConfig& config);
+
+    /// Close and finalize the file.
+    void close();
+    bool isOpened() const;
+
+    /**
+     * @brief Write a single frame.
+     * @param frame The video frame to write. Pixel format will be converted to NV12 internally.
+     * @param timestampNs Optional timestamp in nanoseconds. If 0, auto-increment based on frameRate.
+     * @return true on success, false on failure.
+     */
+    bool writeFrame(const VideoFrame& frame, uint64_t timestampNs = 0);
+
+    /// Query the actual codec being used (may differ from config due to fallback).
+    VideoCodec actualCodec() const;
+
+    uint32_t width() const;
+    uint32_t height() const;
+    double frameRate() const;
+
+    struct Impl;
+
+private:
+    void* m_impl;
+};
+
+} // namespace ccap
+
+#endif // CCAP_WRITER_H

include/ccap_writer_c.h

@@ -0,0 +1,111 @@
+/**
+ * @file ccap_writer_c.h
+ * @author wysaid (this@wysaid.org)
+ * @brief Pure C interface for ccap video writer.
+ * @date 2025-05
+ *
+ * @note Requires CCAP_ENABLE_VIDEO_WRITER to be defined.
+ *       Only available on Windows and macOS.
+ */
+
+#pragma once
+#ifndef CCAP_WRITER_C_H
+#define CCAP_WRITER_C_H
+
+#include "ccap_c.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ========== Forward Declarations ========== */
+
+/** @brief Opaque pointer to ccap::VideoWriter C++ object */
+typedef struct CcapVideoWriter CcapVideoWriter;
+
+/* ========== Enumerations ========== */
+
+/** @brief Video codec enumeration */
+typedef enum {
+    CCAP_VIDEO_CODEC_HEVC = 0,  ///< H.265 / HEVC (preferred)
+    CCAP_VIDEO_CODEC_H264 = 1,  ///< H.264 / AVC (fallback)
+} CcapVideoCodec;
+
+/** @brief Video container format */
+typedef enum {
+    CCAP_VIDEO_FORMAT_MP4 = 0,
+    CCAP_VIDEO_FORMAT_MOV = 1,
+} CcapVideoFormat;
+
+/* ========== Data Structures ========== */
+
+/** @brief Video writer configuration */
+typedef struct {
+    CcapVideoCodec codec;          ///< Preferred codec
+    CcapVideoFormat container;     ///< Container format
+    uint32_t width;                ///< Frame width
+    uint32_t height;               ///< Frame height
+    double frameRate;              ///< Target frame rate (0 = variable)
+    uint64_t bitRate;              ///< Target bit rate in bits/s (0 = auto)
+} CcapWriterConfig;
+
+/* ========== Writer Lifecycle ========== */
+
+/**
+ * @brief Create a new video writer instance
+ * @return Pointer to CcapVideoWriter instance, or NULL on failure
+ */
+CCAP_EXPORT CcapVideoWriter* ccap_video_writer_create(void);
+
+/**
+ * @brief Destroy a video writer instance and finalize the output file
+ * @param writer Pointer to CcapVideoWriter instance
+ */
+CCAP_EXPORT void ccap_video_writer_destroy(CcapVideoWriter* writer);
+
+/**
+ * @brief Open writer to a file path
+ * @param writer Pointer to CcapVideoWriter instance
+ * @param filePath Output file path (e.g., "output.mp4")
+ * @param config Writer configuration
+ * @return true on success, false on failure
+ */
+CCAP_EXPORT bool ccap_video_writer_open(CcapVideoWriter* writer, const char* filePath,
+                                        const CcapWriterConfig* config);
+
+/**
+ * @brief Close and finalize the output file
+ * @param writer Pointer to CcapVideoWriter instance
+ */
+CCAP_EXPORT void ccap_video_writer_close(CcapVideoWriter* writer);
+
+/**
+ * @brief Check if writer is opened
+ * @param writer Pointer to CcapVideoWriter instance
+ * @return true if opened, false otherwise
+ */
+CCAP_EXPORT bool ccap_video_writer_is_opened(const CcapVideoWriter* writer);
+
+/**
+ * @brief Write a single frame
+ * @param writer Pointer to CcapVideoWriter instance
+ * @param frameInfo Frame data to write (must match configured width/height)
+ * @param timestampNs Timestamp in nanoseconds (0 for auto-increment)
+ * @return true on success, false on failure
+ */
+CCAP_EXPORT bool ccap_video_writer_write_frame(CcapVideoWriter* writer,
+                                               const CcapVideoFrameInfo* frameInfo,
+                                               uint64_t timestampNs);
+
+/**
+ * @brief Get the actual codec being used (may differ from config due to fallback)
+ * @param writer Pointer to CcapVideoWriter instance
+ * @return Actual codec enum value
+ */
+CCAP_EXPORT CcapVideoCodec ccap_video_writer_actual_codec(const CcapVideoWriter* writer);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CCAP_WRITER_C_H */

src/ccap_c.cpp

@@ -520,6 +520,17 @@ static_assert(static_cast<uint32_t>(CCAP_ERROR_SEEK_FAILED) == static_cast<uint3
               "C and C++ ErrorCode::SeekFailed values must match");
 static_assert(static_cast<uint32_t>(CCAP_ERROR_INTERNAL_ERROR) == static_cast<uint32_t>(ccap::ErrorCode::InternalError),
               "C and C++ ErrorCode::InternalError values must match");
+// Video writer error code consistency checks
+static_assert(static_cast<uint32_t>(CCAP_ERROR_WRITER_OPEN_FAILED) == static_cast<uint32_t>(ccap::ErrorCode::WriterOpenFailed),
+              "C and C++ ErrorCode::WriterOpenFailed values must match");
+static_assert(static_cast<uint32_t>(CCAP_ERROR_WRITER_WRITE_FAILED) == static_cast<uint32_t>(ccap::ErrorCode::WriterWriteFailed),
+              "C and C++ ErrorCode::WriterWriteFailed values must match");
+static_assert(static_cast<uint32_t>(CCAP_ERROR_WRITER_CLOSE_FAILED) == static_cast<uint32_t>(ccap::ErrorCode::WriterCloseFailed),
+              "C and C++ ErrorCode::WriterCloseFailed values must match");
+static_assert(static_cast<uint32_t>(CCAP_ERROR_WRITER_NOT_OPENED) == static_cast<uint32_t>(ccap::ErrorCode::WriterNotOpened),
+              "C and C++ ErrorCode::WriterNotOpened values must match");
+static_assert(static_cast<uint32_t>(CCAP_ERROR_UNSUPPORTED_CODEC) == static_cast<uint32_t>(ccap::ErrorCode::UnsupportedCodec),
+              "C and C++ ErrorCode::UnsupportedCodec values must match");
 
 // LogLevel enum consistency checks
 static_assert(static_cast<uint32_t>(CCAP_LOG_LEVEL_NONE) == static_cast<uint32_t>(ccap::LogLevel::None),

src/ccap_utils.cpp

@@ -283,6 +283,16 @@ std::string_view errorCodeToString(ErrorCode errorCode) {
         return "Video format is not supported";
     case ErrorCode::SeekFailed:
         return "Seek operation failed";
+    case ErrorCode::WriterOpenFailed:
+        return "Failed to open video writer";
+    case ErrorCode::WriterWriteFailed:
+        return "Failed to write frame";
+    case ErrorCode::WriterCloseFailed:
+        return "Failed to finalize file";
+    case ErrorCode::WriterNotOpened:
+        return "Writer not opened";
+    case ErrorCode::UnsupportedCodec:
+        return "Codec not supported on this platform";
     case ErrorCode::InternalError:
         return "Unknown or internal error";
     default: