capture_source.h

/*
 * Copyright 2026 LiveKit
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an “AS IS” BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
#include "livekit/build.h"
 
// Internal SDK wrappers are built for both variants; consumers require capture.
#if !LIVEKIT_CAPTURE_ENABLED && !defined(LIVEKIT_BUILDING_SDK)
#error "Capture sources require a capture-enabled LiveKit SDK; rebuild with --capture."
#endif
 
#include <cstdint>
#include <future>
#include <memory>
#include <optional>
#include <string>
 
#include "livekit/result.h"
#include "livekit/room_event_types.h"
#include "livekit/video_source.h"
#include "livekit/visibility.h"
 
namespace livekit {
 
class FfiClient;
 
namespace proto {
class OwnedCaptureSource;
} // namespace proto
 
} // namespace livekit
 
namespace livekit::capture {
 
enum class CaptureSourceKind {
  Pixel = 0,
  Encoded = 1,
};
 
enum class GstreamerBitrateUnit {
  Bps = 0,
  Kbps = 1,
};
 
struct CaptureResolution {
  std::uint32_t width = 0;
  std::uint32_t height = 0;
};
 
struct GstreamerRateControl {
  std::string element;
 
  std::string property;
 
  GstreamerBitrateUnit unit = GstreamerBitrateUnit::Bps;
};
 
struct GstreamerVideoSourceConfig {
  std::string pipeline;
 
  std::optional<VideoCodec> codec;
 
  std::optional<CaptureResolution> resolution;
 
  std::optional<GstreamerRateControl> rate_control;
};
 
enum class Pattern {
  Gradient = 0,
  Logo = 1,
};
 
struct PatternVideoSourceConfig {
  CaptureResolution resolution;
 
  std::uint32_t framerate_fps = 0;
 
  Pattern pattern = Pattern::Gradient;
};
 
struct ClockVideoSourceConfig {
  CaptureResolution resolution;
 
  std::uint32_t framerate_fps = 0;
};
 
enum class CaptureExit {
  Stopped = 0,
  EndOfStream = 1,
};
 
enum class CaptureErrorKind {
  Source = 0,
  Rtc = 1,
  Panicked = 2,
};
 
struct CaptureError {
  std::string message;
 
  CaptureErrorKind kind = CaptureErrorKind::Source;
};
 
struct CaptureResult {
  std::uint64_t frames_captured = 0;
 
  CaptureExit exit = CaptureExit::Stopped;
};
 
class LIVEKIT_API CaptureSource {
public:
  [[nodiscard]] static std::future<Result<std::shared_ptr<CaptureSource>, CaptureError>> create(
      const GstreamerVideoSourceConfig& config);
 
  [[nodiscard]] static std::future<Result<std::shared_ptr<CaptureSource>, CaptureError>> create(
      PatternVideoSourceConfig config);
 
  [[nodiscard]] static std::future<Result<std::shared_ptr<CaptureSource>, CaptureError>> create(
      ClockVideoSourceConfig config);
 
  ~CaptureSource();
 
  CaptureSource(const CaptureSource&) = delete;
  CaptureSource& operator=(const CaptureSource&) = delete;
  CaptureSource(CaptureSource&&) = delete;
  CaptureSource& operator=(CaptureSource&&) = delete;
 
  CaptureSourceKind kind() const noexcept;
 
  int width() const noexcept;
 
  int height() const noexcept;
 
  std::optional<VideoCodec> codec() const noexcept;
 
  std::shared_ptr<VideoSource> videoSource() const noexcept;
 
  TrackPublishOptions publishOptions(TrackPublishOptions options = {}) const;
 
  [[nodiscard]] Result<void, CaptureError> start();
 
  [[nodiscard]] Result<void, CaptureError> stop();
 
  [[nodiscard]] std::future<Result<CaptureResult, CaptureError>> join();
 
private:
  friend class livekit::FfiClient;
 
  CaptureSource();
 
  static std::shared_ptr<CaptureSource> fromOwned(const proto::OwnedCaptureSource& owned);
 
  struct Impl;
  std::unique_ptr<Impl> impl_;
};
 
} // namespace livekit::capture