SDK API Reference

This page provides the complete API reference for the monibuca-sdk crate, including all public types, trait interfaces, and commonly used modules.

Quick Import

// Recommended: import all common types at once using prelude
use sdk::prelude::*;

prelude includes:

Category	Types
Plugin Core	Plugin, PluginInfo, PluginState, PluginFactory, PluginCreateFn, PluginExport
Task Management	TaskWork, TaskHandle, ChildTaskHandle
Configuration	ConfigProvider, CommonConfig, TcpConfig, UdpConfig, ConfigReloadable
Stream Management	StreamManagerApi, SharedStreamManager, StreamEvent, StreamManagerStats
Publish/Subscribe	Publisher, Subscriber, Dispatcher, DispatchFrame, SubscriberConfig, SubscribeMode
Frame Data	AVFrame, FrameType, VideoFrameType
Codec	VideoCodec, VideoCodecType, AudioCodec, AudioCodecType
HTTP	HttpHandler, HttpMethod, HttpRequest, HttpResponse, HttpRoute, HttpRouteProvider
Error	MonibucaError, Result
Event	EventBus, EventEnvelope, EventPriority
Network	TcpSplitter
Third-party Re-exports	async_trait, Bytes, BytesMut, CancellationToken, Mutex, RwLock, Serialize, Deserialize
Logging	tracing::info!, warn!, error!, debug!, trace!

---

Plugin Trait

#[async_trait]
pub trait Plugin: Send + Sync {
    fn info(&self) -> PluginInfo;
    fn state(&self) -> PluginState;
    async fn init(&mut self, manager: Arc<dyn StreamManagerApi>,
                  config: Arc<dyn ConfigProvider>) -> Result<()>;
    async fn start(&mut self, cancel: CancellationToken) -> Result<()>;
    async fn stop(&mut self) -> Result<()>;
    fn as_any(&self) -> &dyn Any;
    fn as_any_mut(&mut self) -> &mut dyn Any;

    // Optional methods (have default implementations)
    fn name(&self) -> &'static str;
    fn is_enabled(&self) -> bool;
    fn on_config_update(&mut self, config: &serde_json::Value) -> Result<()>;
    fn set_task_work(&mut self, work: Arc<dyn TaskWork>);
    fn set_engine_context(&mut self, ctx: EngineContext);
    fn http_routes(&self) -> Vec<HttpRoute>;
    fn register_http_handlers(&mut self, server: SharedHttpServer);
}

PluginInfo

pub struct PluginInfo {
    pub name: &'static str,
    pub version: &'static str,
    pub description: &'static str,
    pub author: &'static str,
}

PluginState

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PluginState {
    Created,
    Initialized,
    Running,
    Stopped,
    Disabled,
    Error,
}

---

StreamManagerApi Trait

#[async_trait]
pub trait StreamManagerApi: Send + Sync + 'static {
    // ── Publish ──────────────────────────────────────────────────
    fn create_publisher(&self, path: &str)
        -> Result<Arc<RwLock<dyn Publisher>>>;
    fn create_publisher_with_dispatcher(&self, path: &str)
        -> Result<(Arc<RwLock<dyn Publisher>>, Arc<dyn Dispatcher>)>;
    fn create_publisher_for_plugin(&self, path: &str, plugin_name: &str)
        -> Result<Arc<RwLock<dyn Publisher>>>;
    fn get_publisher(&self, path: &str)
        -> Option<Arc<RwLock<dyn Publisher>>>;
    fn get_dispatcher(&self, path: &str)
        -> Option<Arc<dyn Dispatcher>>;

    // ── Subscribe ────────────────────────────────────────────────
    async fn subscribe(&self, path: &str, config: SubscriberConfig)
        -> Result<(Arc<RwLock<dyn Publisher>>, Box<dyn Subscriber>)>;
    fn subscribe_sync(&self, path: &str, config: SubscriberConfig)
        -> Result<(Arc<RwLock<dyn Publisher>>, Box<dyn Subscriber>)>;
    fn unsubscribe(&self, path: &str, subscriber: &mut dyn Subscriber);

    // ── Query ────────────────────────────────────────────────────
    fn has_stream(&self, path: &str) -> bool;
    fn stream_count(&self) -> usize;
    fn stream_paths(&self) -> Vec<String>;
    fn stats(&self) -> StreamManagerStats;
    fn video_track(&self, path: &str) -> Option<Arc<dyn VideoTrack>>;
    fn audio_track(&self, path: &str) -> Option<Arc<dyn AudioTrack>>;

    // ── Events ───────────────────────────────────────────────────
    fn subscribe_events(&self) -> broadcast::Receiver<StreamEvent>;

    // ── Lifecycle ────────────────────────────────────────────────
    fn dispose_stream(&self, path: &str) -> bool;
    fn force_dispose_stream(&self, path: &str) -> bool;
    fn is_running(&self) -> bool;
}

StreamEvent

pub enum StreamEvent {
    Created(String),                            // Stream path
    Disposed(String),                           // Stream path
    SubscriberAdded { stream: String, .. },     // New subscriber joined
    SubscriberRemoved { stream: String, .. },   // Subscriber left
}

---

Publisher Trait

pub trait Publisher: Send + Sync {
    fn path(&self) -> &str;
    fn subscriber_count(&self) -> usize;
    fn plugin_name(&self) -> &str;
    fn set_plugin_name(&mut self, name: &str);
    fn state(&self) -> PublisherState;

    // Track initialization
    fn init_video_track(&mut self);
    fn init_audio_track(&mut self);

    // Codec setup
    fn set_video_codec(&mut self, codec: VideoCodec);
    fn set_audio_codec(&mut self, codec: AudioCodec);
    fn set_video_seq_header(&mut self, data: Bytes);
    fn set_audio_seq_header(&mut self, data: Bytes);
    fn video_seq_header(&self) -> Option<Bytes>;
    fn audio_seq_header(&self) -> Option<Bytes>;
    fn audio_codec(&self) -> Option<AudioCodec>;

    // Frame writing
    fn write_video(&self, frame_type: VideoFrameType,
                   pts: Duration, dts: Duration, data: Bytes) -> Result<()>;
    fn write_video_raw(&self, frame_type: VideoFrameType,
                       timestamp: Duration, dts: Duration,
                       nalus: Vec<Bytes>) -> Result<()>;
    fn write_audio(&self, timestamp: Duration, data: Bytes) -> Result<()>;

    // Lifecycle
    fn dispose(&self);

    // Extra parameters
    fn set_extra_param(&mut self, key: &str, value: &str);
    fn set_extra_params(&mut self, params: HashMap<String, String>);
}

---

Subscriber Trait

pub trait Subscriber: Send + Sync {
    fn id(&self) -> u64;
    fn path(&self) -> &str;
    fn mode(&self) -> SubscribeMode;

    // Async waiting
    fn wait_for_frames(&mut self)
        -> Pin<Box<dyn Future<Output = Result<()>> + Send + '_>>;

    // Frame reading
    fn read_video(&mut self) -> Result<Option<AVFrame>>;
    fn read_audio(&mut self) -> Option<AVFrame>;

    // State query
    fn is_stopped(&self) -> bool;
    fn has_video(&self) -> bool;
    fn has_audio(&self) -> bool;

    // Lifecycle
    fn unsubscribe(&mut self, publisher: &dyn Publisher);
}

SubscriberConfig

pub struct SubscriberConfig {
    pub mode: SubscribeMode,
    pub buffer_time: Duration,           // Default 2s
    pub receive_video: bool,             // Default true
    pub receive_audio: bool,             // Default true
    pub keyframe_timeout: Option<Duration>,  // Default Some(30s)
}

pub enum SubscribeMode {
    RealTime,      // Start from the latest IDR keyframe
    Buffer,        // Start from the IDR buffer_time ago
    WaitKeyframe,  // Wait for the next keyframe
}

---

AVFrame

pub struct AVFrame {
    pub timestamp: Duration,
    pub video_frame_type: VideoFrameType,
    pub video_codec: Option<Arc<VideoCodec>>,
    pub audio_codec: Option<AudioCodec>,
    // ... internal fields
}

impl AVFrame {
    // Video format conversion (lazy-loaded cache)
    pub fn get_flv_video_tag(&self) -> Bytes;
    pub fn get_annexb(&self) -> Bytes;
    pub fn get_avcc(&self) -> Bytes;
    pub fn get_raw(&self) -> Bytes;
    pub fn is_keyframe(&self) -> bool;

    // Audio format conversion
    pub fn get_flv_audio_tag(&self) -> Bytes;
    pub fn get_audio_raw(&self) -> Bytes;
}

---

HTTP System

HttpRequest

pub struct HttpRequest {
    pub method: String,
    pub path: String,
    pub query: Option<String>,
    pub headers: HashMap<String, String>,
    pub body: Bytes,
    pub params: HashMap<String, String>,
    pub peer_addr: SocketAddr,
}

impl HttpRequest {
    pub fn body_str(&self) -> Option<&str>;
    pub fn parse_json_body<T: DeserializeOwned>(&self) -> Result<T>;
    pub fn query_param(&self, key: &str) -> Option<String>;
    pub fn path_param(&self, key: &str) -> Option<String>;
}

HttpResponse

impl HttpResponse {
    // Constructors
    pub fn ok() -> Self;                   // 200
    pub fn not_found() -> Self;            // 404
    pub fn bad_request() -> Self;          // 400
    pub fn internal_error() -> Self;       // 500
    pub fn new(status: u16) -> Self;       // Custom status code

    // Builder methods
    pub fn json<T: Serialize>(self, data: &T) -> Self;
    pub fn text(self, text: &str) -> Self;
    pub fn body(self, data: Bytes) -> Self;
    pub fn content_type(self, ct: &str) -> Self;
    pub fn header(self, key: &str, value: &str) -> Self;
    pub fn cors_origin(self, origin: &str) -> Self;
}

HttpRoute & HttpHandler

pub struct HttpRoute {
    pub method: HttpMethod,
    pub path: String,           // Supports wildcards: "/api/**"
    pub handler: Box<dyn HttpHandler>,
}

pub enum HttpMethod { Get, Post, Put, Delete, Patch, Options, Head }

#[async_trait]
pub trait HttpHandler: Send + Sync {
    async fn handle(&self, req: HttpRequest) -> HttpResponse;
}

---

EngineContext

pub struct EngineContext { /* TypeId-keyed map */ }

impl EngineContext {
    // Generic API
    pub fn set<T: Any + Send + Sync>(&mut self, value: T);
    pub fn get<T: Any + Send + Sync>(&self) -> Option<&T>;
    pub fn has<T: Any + Send + Sync>(&self) -> bool;

    // Predefined capabilities
    pub fn database_arc(&self) -> Option<Arc<dyn DatabaseApi>>;
    pub fn transform(&self) -> Option<Arc<dyn TransformApi>>;
    pub fn playback(&self) -> Option<Arc<dyn PlaybackApi>>;
    pub fn service_registry(&self) -> Option<Arc<dyn ServiceRegistry>>;
    pub fn room_api(&self) -> Option<Arc<dyn RoomApi>>;
    pub fn proxy_manager(&self) -> Option<Arc<dyn ProxyManager>>;
    pub fn collection(&self) -> Option<Arc<dyn CollectionApi>>;
    pub fn reporting(&self) -> Option<Arc<dyn ReportingApi>>;
    pub fn utility_provider(&self) -> Option<Arc<dyn UtilityProvider>>;
    pub fn http_registry(&self) -> Option<Arc<dyn HttpRegistry>>;

    // Check methods
    pub fn has_database(&self) -> bool;
    pub fn has_transform(&self) -> bool;
    pub fn has_playback(&self) -> bool;
    pub fn has_service_registry(&self) -> bool;
    pub fn has_room_api(&self) -> bool;
    pub fn has_proxy_manager(&self) -> bool;
    pub fn has_collection(&self) -> bool;
    pub fn has_reporting(&self) -> bool;
    pub fn has_utility_provider(&self) -> bool;
    pub fn has_http_registry(&self) -> bool;
}

---

TaskWork System

pub trait TaskWork: Send + Sync + Any {
    fn start(&self);
    fn register_child(&self, owner: &str, task: Pin<Box<dyn Future<Output=()> + Send>>);
    fn create_child_task(&self, owner: &str) -> Box<dyn ChildTaskHandle>;
    fn remove_child_task(&self, child_id: u64);
    fn task(&self) -> Option<Arc<dyn TaskHandle>>;
}

pub trait ChildTaskHandle: Send + Sync + Any {
    fn start(&self);
    fn stop(&self);
    fn id(&self) -> u64;
    fn cancellation_token(&self) -> CancellationToken;
}

---

ConfigProvider Trait

pub trait ConfigProvider: Send + Sync + Any {
    fn get(&self, key: &str) -> Option<serde_json::Value>;
    fn get_plugin_config(&self, plugin_name: &str) -> Option<serde_json::Value>;
    fn load_default_config(&self, plugin_name: &str, default_yaml: &str) -> Result<()>;
    fn is_plugin_enabled(&self, plugin_name: &str) -> bool;
    fn get_cors_config(&self) -> (bool, Vec<String>);
}

---

ServiceRegistry

pub trait ServiceRegistry: Send + Sync {
    // Protocol factory registration
    fn register_puller_factory(&self, factory: Arc<dyn PullerFactory>);
    fn register_pusher_factory(&self, factory: Arc<dyn PusherFactory>);

    // Protocol factory lookup
    fn get_puller_factory(&self, protocol: &str) -> Option<Arc<dyn PullerFactory>>;
    fn get_pusher_factory(&self, protocol: &str) -> Option<Arc<dyn PusherFactory>>;
    fn get_puller_factory_for_url(&self, url: &str) -> Option<Arc<dyn PullerFactory>>;
    fn get_pusher_factory_for_url(&self, url: &str) -> Option<Arc<dyn PusherFactory>>;

    // List registered protocols
    fn list_puller_protocols(&self) -> Vec<String>;
    fn list_pusher_protocols(&self) -> Vec<String>;

    // Generic service registration (Any type)
    fn register_service(&self, name: &str, service: Arc<dyn Any + Send + Sync>);
    fn get_service(&self, name: &str) -> Option<Arc<dyn Any + Send + Sync>>;
}

PullerFactory / PusherFactory

#[async_trait]
pub trait PullerFactory: Send + Sync {
    fn protocol(&self) -> &str;
    fn supports_url(&self, url: &str) -> bool;
    async fn create_puller(
        &self, url: &str, stream_path: &str,
        config: serde_json::Value,
        manager: Arc<dyn StreamManagerApi>,
        cancel_token: CancellationToken,
    ) -> Result<Arc<tokio::sync::RwLock<Box<dyn StreamPuller>>>>;
}

#[async_trait]
pub trait PusherFactory: Send + Sync {
    fn protocol(&self) -> &str;
    fn supports_url(&self, url: &str) -> bool;
    async fn create_pusher(
        &self, url: &str, stream_path: &str,
        config: serde_json::Value,
        manager: Arc<dyn StreamManagerApi>,
        cancel_token: CancellationToken,
    ) -> Result<Arc<tokio::sync::RwLock<Box<dyn StreamPusher>>>>;
}

#[async_trait]
pub trait StreamPuller: Send + Sync {
    async fn start(&mut self) -> Result<()>;
    fn stop(&self) -> Result<()>;
    fn stream_path(&self) -> &str;
    fn is_running(&self) -> bool;
}

#[async_trait]
pub trait StreamPusher: Send + Sync {
    async fn start(&mut self) -> Result<()>;
    fn stop(&self) -> Result<()>;
    fn stream_path(&self) -> &str;
    fn is_running(&self) -> bool;
}

---

Network Utilities

/// Create a TCP listener with SO_REUSEPORT enabled
pub fn create_tcp_listener(addr: SocketAddr) -> std::io::Result<TcpListener>;

/// TCP byte stream framing trait
pub trait TcpSplitter: Send {
    fn split(&mut self, data: &[u8]) -> Vec<Vec<u8>>;
    fn pending(&self) -> &[u8];
    fn clear(&mut self);
}

---

EventBus

#[async_trait]
pub trait EventBus: Send + Sync {
    async fn register_user(&self, room_id: &str, user_id: String,
        sender: mpsc::UnboundedSender<Bytes>) -> Result<()>;
    async fn unregister_user(&self, room_id: &str, user_id: &str) -> Result<()>;
    async fn dispatch_event<T: Serialize + Send + Sync>(
        &self, room_id: &str, target_user_id: Option<&str>,
        event_type: &str, data: &T) -> Result<()>;
    async fn broadcast_event<T: Serialize + Send + Sync>(
        &self, room_id: &str, event_type: &str, data: &T) -> Result<()>;
}

pub struct EventEnvelope {
    pub event_type: String,
    pub seq: Option<u64>,
    pub timestamp: Option<i64>,
    pub sender_id: Option<String>,
    pub data: serde_json::Value,
}

---

Error Types

pub enum MonibucaError {
    Plugin(String),          // Plugin custom error
    Io(std::io::Error),      // IO error
    Config(String),          // Configuration error
    Stream(String),          // Stream operation error
    Codec(String),           // Codec error
    // ... other variants
}

pub type Result<T> = std::result::Result<T, MonibucaError>;

---

Codec Types

pub enum VideoCodecType { H264, H265, AV1, VP8, VP9, }
pub enum AudioCodecType { AAC, Opus, G711A, G711U, MP3, }
pub enum VideoFrameType { Keyframe, Interframe, }

pub struct VideoCodec {
    pub codec_type: VideoCodecType,
    pub width: u32,
    pub height: u32,
    // ...
}

impl VideoCodec {
    pub fn new(codec_type: VideoCodecType, width: u32, height: u32) -> Self;
    pub fn with_record(self, data: Bytes) -> Self;
}

pub struct AudioCodec {
    pub codec_type: AudioCodecType,
    pub sample_rate: u32,
    pub channels: u8,
}

impl AudioCodec {
    pub fn new(codec_type: AudioCodecType, sample_rate: u32, channels: u8) -> Self;
}

---

Macros

export_plugin!

sdk::export_plugin!(MyPlugin);
// Requires MyPlugin: Default + Plugin
// Generates C ABI symbols: plugin_api_version, plugin_create, plugin_metadata

ConfigSchema derive

#[derive(ConfigSchema)]
#[schema(plugin = "name", title = "Title", description = "Desc", sdk_path = "sdk")]
pub struct MyConfig { /* ... */ }

monibuca_plugin attribute macro

#[monibuca_plugin(name = "my-plugin", version = "0.1.0")]
pub struct MyPlugin { /* ... */ }
// Automatically generates Default implementation + PLUGIN_NAME/PLUGIN_VERSION constants