update the code to adapt the style / apis like other sdk

Author: xianshijing-lk

examples/simple_room/main.cpp

@@ -278,15 +278,15 @@ int main(int argc, char *argv[]) {
   options.dynacast = false;
 
   if (enable_e2ee) {
-    livekit::E2EEOptions e2ee;
-    e2ee.encryption_type = livekit::EncryptionType::GCM;
+    livekit::E2EEOptions encryption;
+    encryption.encryption_type = livekit::EncryptionType::GCM;
     // Optional shared key: if empty, we enable E2EE without setting a shared
     // key. (Advanced use: keys can be set/ratcheted later via
     // E2EEManager/KeyProvider.)
     if (!e2ee_key.empty()) {
-      e2ee.shared_key = toBytes(e2ee_key);
+      encryption.key_provider_options.shared_key = toBytes(e2ee_key);
     }
-    options.e2ee = e2ee;
+    options.encryption = encryption;
     if (!e2ee_key.empty()) {
       std::cout << "[E2EE] enabled : (shared key length=" << e2ee_key.size()
                 << ")\n";
@@ -385,19 +385,23 @@ int main(int argc, char *argv[]) {
     std::this_thread::sleep_for(std::chrono::milliseconds(10));
   }
 
-  // Shutdown the audio thread.
+  // Shutdown the audio / video capture threads.
   media.stopMic();
+  media.stopCamera();
+
+  // Drain any queued tasks that might still try to update the renderer /
+  // speaker
+  MainThreadDispatcher::update();
+
+  // Must be cleaned up before FfiClient::instance().shutdown();
+  room->setDelegate(nullptr);
 
   // Clean up the audio track publishment
   room->localParticipant()->unpublishTrack(audioPub->sid());
 
-  media.stopCamera();
-
   // Clean up the video track publishment
   room->localParticipant()->unpublishTrack(videoPub->sid());
 
-  // Must be cleaned up before FfiClient::instance().shutdown();
-  room->setDelegate(nullptr);
   room.reset();
 
   FfiClient::instance().shutdown();

include/livekit/e2ee.h

@@ -24,143 +24,198 @@
 
 namespace livekit {
 
-/* Encryption algorithm type used by the underlying stack. Keep this aligned
- * with your proto enum. */
-enum class EncryptionType { NONE = 0, GCM = 1, CUSTOM = 2 };
-
-/// End-to-end encryption (E2EE) configuration.
-///
-/// When enabled, media frames are encrypted before being sent and
-/// decrypted on receipt. Keys may be provided up-front (shared-key mode)
-/// or supplied by other mechanisms supported by the underlying runtime.
-struct E2EEOptions {
-  bool enabled;
-  /// Encryption algorithm to use.
-  ///
-  /// GCM is the default and recommended option.
-  EncryptionType encryption_type = EncryptionType::GCM;
+/* Encryption algorithm type used by the underlying stack.
+ * Keep this aligned with your proto enum values. */
+enum class EncryptionType {
+  NONE = 0,
+  GCM = 1,
+  CUSTOM = 2,
+};
 
-  /// Shared static key for shared-key E2EE.
+/* Defaults (match other SDKs / Python defaults). */
+inline constexpr const char *kDefaultRatchetSalt = "LKFrameEncryptionKey";
+inline constexpr int kDefaultRatchetWindowSize = 16;
+inline constexpr int kDefaultFailureTolerance = -1;
+
+/**
+ * Options for configuring the key provider used by E2EE.
+ *
+ * Notes:
+ * - `shared_key` is optional. If omitted, the application may set keys later
+ *   (e.g. via KeyProvider::setSharedKey / per-participant keys).
+ * - `ratchet_salt` may be empty to indicate "use implementation default".
+ * - `ratchet_window_size` and `failure_tolerance` use SDK defaults unless
+ * overridden.
+ */
+struct EncryptionKeyProviderOptions {
+  /// Shared static key for "shared-key E2EE" (optional).
   ///
-  /// When using shared-key E2EE, this key must be provided and must be
-  /// identical (byte-for-byte) for all participants in the room in order
-  /// to successfully encrypt and decrypt media.
+  /// If set, it must be identical (byte-for-byte) across all participants
+  /// that are expected to decrypt each other’s media.
   ///
-  /// If this is empty while E2EE is enabled, media cannot be decrypted
-  /// and participants will not be able to communicate (e.g. black video /
-  /// silent audio).
-  std::vector<std::uint8_t> shared_key;
+  /// If not set, keys must be provided out-of-band later (e.g. via KeyProvider
+  /// APIs).
+  std::optional<std::vector<std::uint8_t>> shared_key;
 
-  /// Optional salt used when deriving ratcheted encryption keys.
+  /// Salt used when deriving ratcheted keys.
   ///
-  /// If empty, a default salt is used by the underlying implementation.
-  std::vector<std::uint8_t> ratchet_salt;
+  /// If empty, the underlying implementation default is used.
+  std::vector<std::uint8_t> ratchet_salt = std::vector<std::uint8_t>(
+      kDefaultRatchetSalt, kDefaultRatchetSalt + std::char_traits<char>::length(
+                                                     kDefaultRatchetSalt));
 
-  /// Optional ratchet window size.
-  ///
   /// Controls how many previous keys are retained during ratcheting.
-  /// A value of 0 indicates that the implementation default is used.
-  int ratchet_window_size = 0;
+  int ratchet_window_size = kDefaultRatchetWindowSize;
 
-  /// Optional failure tolerance for ratcheting.
-  ///
-  /// Specifies how many consecutive ratcheting failures are tolerated
-  /// before encryption errors are reported. A value of 0 indicates
-  /// that the implementation default is used.
-  int failure_tolerance = 0;
+  /// Number of tolerated ratchet failures before reporting encryption errors.
+  int failure_tolerance = kDefaultFailureTolerance;
+};
+
+/**
+ * End-to-end encryption (E2EE) configuration for a room.
+ *
+ * Provide this in RoomOptions to initialize E2EE support.
+ *
+ * IMPORTANT:
+ * - Providing E2EEOptions means "E2EE support is configured for this room".
+ * - Whether encryption is actively applied can still be toggled at runtime via
+ *   E2EEManager::setEnabled().
+ * - A room can be configured for E2EE even if no shared key is provided yet.
+ *   In that case, the app must supply keys later via KeyProvider (shared-key or
+ *   per-participant).
+ */
+struct E2EEOptions {
+  EncryptionKeyProviderOptions key_provider_options{};
+  EncryptionType encryption_type = EncryptionType::GCM; // default & recommended
 };
 
+/**
+ * E2EE manager for a connected room.
+ *
+ * Lifetime:
+ * - Owned by Room. Applications must not construct E2EEManager directly.
+ *
+ * Enablement model:
+ * - If the Room was created with `RoomOptions.e2ee` set, the room will expose
+ *   a non-null E2EEManager via Room::E2eeManager().
+ * - If the Room was created without E2EE options, Room::E2eeManager() may be
+ * null.
+ *
+ * Key model:
+ * - Keys are managed via KeyProvider (shared-key or per-participant).
+ * - Providing a shared key up-front is convenient for shared-key E2EE, but is
+ * not required by the API shape (keys may be supplied later).
+ */
 class E2EEManager {
 public:
-  virtual ~E2EEManager();
-
+  /** If your application requires key rotation during the lifetime of a single
+   * room or unique keys per participant (such as when implementing the MEGOLM
+   * or MLS protocol), you' can do it via key provider and frame cryptor. refer
+   * https://docs.livekit.io/home/client/encryption/#custom-key-provider doe
+   * details
+   *  */
+  class KeyProvider {
+  public:
+    ~KeyProvider() = default;
+
+    KeyProvider(const KeyProvider &) = delete;
+    KeyProvider &operator=(const KeyProvider &) = delete;
+    KeyProvider(KeyProvider &&) noexcept = default;
+    KeyProvider &operator=(KeyProvider &&) noexcept = default;
+
+    /// Returns the options used to initialize this KeyProvider.
+    const EncryptionKeyProviderOptions &options() const;
+
+    /// Sets the shared key for the given key slot.
+    void setSharedKey(const std::vector<std::uint8_t> &key, int key_index = 0);
+
+    /// Exports the shared key for a given key slot.
+    std::vector<std::uint8_t> exportSharedKey(int key_index = 0) const;
+
+    /// Ratchets the shared key at key_index and returns the newly derived key.
+    std::vector<std::uint8_t> ratchetSharedKey(int key_index = 0);
+
+    /// Sets a key for a specific participant identity.
+    void setKey(const std::string &participant_identity,
+                const std::vector<std::uint8_t> &key, int key_index = 0);
+
+    /// Exports a participant-specific key.
+    std::vector<std::uint8_t> exportKey(const std::string &participant_identity,
+                                        int key_index = 0) const;
+
+    /// Ratchets a participant-specific key and returns the new key.
+    std::vector<std::uint8_t>
+    ratchetKey(const std::string &participant_identity, int key_index = 0);
+
+  private:
+    friend class E2EEManager;
+    KeyProvider(std::uint64_t room_handle,
+                EncryptionKeyProviderOptions options);
+    std::uint64_t room_handle_{0};
+    EncryptionKeyProviderOptions options_;
+  };
+
+  class FrameCryptor {
+  public:
+    FrameCryptor(std::uint64_t room_handle, std::string participant_identity,
+                 int key_index, bool enabled);
+    ~FrameCryptor() = default;
+    FrameCryptor(const FrameCryptor &) = delete;
+    FrameCryptor &operator=(const FrameCryptor &) = delete;
+    FrameCryptor(FrameCryptor &&) noexcept = default;
+    FrameCryptor &operator=(FrameCryptor &&) noexcept = default;
+
+    const std::string &participantIdentity() const;
+    int keyIndex() const;
+    bool enabled() const;
+
+    /// Enables or disables frame encryption/decryption for this participant.
+    void setEnabled(bool enabled);
+
+    /// Sets the active key index for this participant cryptor.
+    void setKeyIndex(int key_index);
+
+  private:
+    std::uint64_t room_handle_{0};
+    bool enabled_{false};
+    std::string participant_identity_;
+    int key_index_{0};
+  };
+
+  ~E2EEManager() = default;
   E2EEManager(const E2EEManager &) = delete;
   E2EEManager &operator=(const E2EEManager &) = delete;
+  E2EEManager(E2EEManager &&) noexcept = delete;
+  E2EEManager &operator=(E2EEManager &&) noexcept = delete;
 
-  E2EEManager(E2EEManager &&) noexcept;
-  E2EEManager &operator=(E2EEManager &&) noexcept;
-
-  /**
-   * Returns whether end-to-end encryption (E2EE) is currently enabled.
-   *
-   * This reflects the runtime encryption state for media tracks
-   * associated with the room.
-   */
+  /// Returns whether E2EE is currently enabled for this room at runtime.
   bool enabled() const;
 
-  /**
-   * Enable or disable end-to-end encryption at runtime.
-   *
-   * Disabling E2EE will stop encrypting outgoing media and stop
-   * decrypting incoming media.
-   *
-   * NOTE:
-   * - All participants must agree on E2EE state and keys in order
-   *   to successfully exchange media.
-   * - Disabling E2EE while other participants still have it enabled
-   *   will result in media being undecodable.
-   */
+  /// Enable or disable E2EE at runtime.
+  ///
+  /// NOTE:
+  /// - Enabling E2EE without having compatible keys set across participants
+  ///   will result in undecodable media (black video / silent audio).
   void setEnabled(bool enabled);
 
-  /**
-   * Set or replace the shared encryption key at the given key index.
-   *
-   * This is typically used for:
-   * - Manual key rotation
-   *
-   * The provided key MUST be identical across all participants
-   * using shared-key E2EE, otherwise media decryption will fail.
-   *
-   * @param key        Raw key bytes
-   * @param key_index Index of the key to set (default: 0)
-   */
-  void setSharedKey(const std::vector<std::uint8_t> &key, int key_index = 0);
-
-  /**
-   * Export the currently active shared key at the given key index.
-   *
-   * This API is primarily intended for debugging, verification,
-   * or diagnostics. Applications should avoid exporting keys
-   * unless absolutely necessary.
-   *
-   * @param key_index Index of the key to export (default: 0)
-   * @return          Raw key bytes
-   */
-  std::vector<std::uint8_t> exportSharedKey(int key_index = 0) const;
-
-  /**
-   * Ratchet (derive) a new shared key at the given key index.
-   *
-   * This advances the key forward and returns the newly derived key.
-   * All participants must ratchet keys in the same order to remain
-   * in sync.
-   *
-   * @param key_index Index of the key to ratchet (default: 0)
-   * @return          Newly derived key bytes
-   */
-  std::vector<std::uint8_t> ratchetSharedKey(int key_index = 0);
+  /// Returns the key provider if E2EE was configured for the room; otherwise
+  /// nullptr.
+  KeyProvider *keyProvider();
+  const KeyProvider *keyProvider() const;
+
+  /// Retrieves the current list of frame cryptors from the underlying runtime.
+  std::vector<E2EEManager::FrameCryptor> frameCryptors() const;
 
 protected:
-  /*
-   * Construct an E2EE manager for a connected room.
-   *
-   * This constructor are intended for internal use by room.
-   * Applications should NOT create their own E2EEManager instances.
-   *
-   * After successfully connecting to a room with E2EE enabled,
-   * obtain the E2EE manager via the Room:
-   *
-   *   auto e2ee_manager = room->e2eeManager();
-   *
-   * The Room owns and manages the lifetime of the E2EEManager and ensures
-   * it is correctly wired to the underlying room handle and track lifecycle.
-   */
-  explicit E2EEManager(std::uint64_t room_handle, E2EEOptions config);
+  /// Internal constructor used by Room when E2EEOptions are provided.
+  explicit E2EEManager(std::uint64_t room_handle, const E2EEOptions &options);
   friend class Room;
 
 private:
-  struct Impl;
-  std::unique_ptr<Impl> impl_;
+  std::uint64_t room_handle_{0};
+  bool enabled_{false};
+  E2EEOptions options_;
+  KeyProvider key_provider_;
 };
 
 } // namespace livekit

include/livekit/room.h

@@ -73,11 +73,11 @@ struct RoomOptions {
   // Enable dynacast (server sends optimal layers depending on subscribers).
   bool dynacast = false;
 
-  // Optional end-to-end encryption settings.
-  std::optional<E2EEOptions> e2ee;
-
   // Optional WebRTC configuration (ICE policy, servers, etc.)
   std::optional<RtcConfig> rtc_config;
+
+  // Optional end-to-end encryption settings.
+  std::optional<E2EEOptions> encryption;
 };
 
 /// Represents a LiveKit room session.