feat(codec): implement software H.264 encode/decode round-trip

Add FFmpeg-based encoder/decoder with SPS/PPS extradata, Annex-B output

normalization, low-latency libx264 settings, and a round-trip unit test.

Includes review hardening: cached SwsContext, bitrate-only rate control,

std::byte/uin8_t cast helpers, and richer test assertions.

include/screencast/codec/decoder.h

@@ -1,11 +1,11 @@
 #pragma once
 
 #include "screencast/codec/encoder.h"
+#include "screencast/codec/error.h"
 
 #include <cstdint>
 #include <memory>
-#include <optional>
-#include <span>
+#include <string>
 #include <vector>
 
 namespace sc {
@@ -18,22 +18,23 @@ struct DecodedFrame {
 };
 
 struct DecoderConfig {
-    std::string_view codec_name = "h264";
+    std::string codec_name = "h264";
     int width = 0;
     int height = 0;
+    std::vector<std::byte> extradata; // SPS/PPS for H.264
 };
 
 class Decoder {
   public:
-    virtual ~Decoder () = default;
+    virtual ~Decoder() = default;
 
     // Feed one encoded frame. Returns decoded frames when available.
-    virtual std::vector<DecodedFrame> decode ( const EncodedFrame &frame ) = 0;
+    virtual CodecResult<std::vector<DecodedFrame>> decode(const EncodedFrame& frame) = 0;
 };
 
 class DecoderFactory {
   public:
-    static std::unique_ptr<Decoder> create ( const DecoderConfig &config );
+    static CodecResult<std::unique_ptr<Decoder>> create(const DecoderConfig& config);
 };
 
-}  // namespace sc
+} // namespace sc

include/screencast/codec/encoder.h

@@ -1,11 +1,11 @@
 #pragma once
 
 #include "screencast/capture/capture.h"
+#include "screencast/codec/error.h"
 
 #include <cstdint>
 #include <memory>
-#include <span>
-#include <string_view>
+#include <string>
 #include <vector>
 
 namespace sc {
@@ -14,11 +14,11 @@ struct EncodedFrame {
     uint64_t capture_timestamp_ns = 0;
     uint32_t rtp_timestamp = 0;
     bool is_keyframe = false;
-    std::vector<std::byte> data;  // Annex-B or AVCC depending on config
+    std::vector<std::byte> data; // Annex-B H.264 NAL units
 };
 
 struct EncoderConfig {
-    std::string_view codec_name = "h264";
+    std::string codec_name = "h264";
     int width = 0;
     int height = 0;
     int frame_rate_num = 30;
@@ -29,19 +29,25 @@ struct EncoderConfig {
 
 class Encoder {
   public:
-    virtual ~Encoder () = default;
+    virtual ~Encoder() = default;
 
-    // Encode one captured frame. Returns empty if the encoder emits no packet
-    // for this frame.
-    virtual std::vector<EncodedFrame> encode ( const CapturedFrame &frame ) = 0;
+    // Encode one captured frame. Returns an empty vector if the encoder emits
+    // no packet for this frame.
+    virtual CodecResult<std::vector<EncodedFrame>> encode(const CapturedFrame& frame) = 0;
 
-    // Force the next output to be a keyframe.
-    virtual void request_keyframe () = 0;
+    // Flush the encoder and return any remaining packets.
+    virtual CodecResult<std::vector<EncodedFrame>> flush() = 0;
+
+    // Force the next output frame to be a keyframe.
+    virtual void request_keyframe() = 0;
+
+    // Codec-specific parameters required by a decoder (SPS/PPS for H.264).
+    virtual std::vector<std::byte> get_extradata() const = 0;
 };
 
 class EncoderFactory {
   public:
-    static std::unique_ptr<Encoder> create ( const EncoderConfig &config );
+    static CodecResult<std::unique_ptr<Encoder>> create(const EncoderConfig& config);
 };
 
-}  // namespace sc
+} // namespace sc

include/screencast/codec/error.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <string>
+#include <variant>
+
+namespace sc {
+
+struct CodecError {
+    std::string message;
+};
+
+// C++20 does not provide std::expected. Use a variant-based result type so
+// fallible codec operations do not rely on exceptions.
+template <typename T> using CodecResult = std::variant<T, CodecError>;
+
+template <typename T> constexpr bool is_codec_error(const CodecResult<T>& result) noexcept {
+    return std::holds_alternative<CodecError>(result);
+}
+
+template <typename T> T& codec_value(CodecResult<T>& result) {
+    return std::get<T>(result);
+}
+
+template <typename T> const T& codec_value(const CodecResult<T>& result) {
+    return std::get<T>(result);
+}
+
+template <typename T> CodecError& codec_error(CodecResult<T>& result) {
+    return std::get<CodecError>(result);
+}
+
+template <typename T> const CodecError& codec_error(const CodecResult<T>& result) {
+    return std::get<CodecError>(result);
+}
+
+} // namespace sc