Improve log messages around plugin loading

.changeset/improve_log_messages_around_plugin_loading.md

@@ -0,0 +1,6 @@
+---
+livekit: patch
+livekit-ffi: patch
+---
+
+Improve log messages around plugin loading - #1186 (@lukasIO)

livekit-ffi/src/server/room.rs

@@ -16,7 +16,7 @@ use std::collections::HashMap;
 use std::time::Duration;
 use std::{collections::HashSet, slice, sync::Arc};
 
-use livekit::{prelude::*, registered_audio_filter_plugins};
+use livekit::{prelude::*, registered_audio_filter_plugins, PluginError};
 use livekit::{ChatMessage, StreamReader};
 use livekit_protocol as lk_proto;
 use parking_lot::Mutex;
@@ -153,22 +153,27 @@ impl FfiRoom {
                         .async_runtime
                         .spawn_blocking(move || {
                             for filter in registered_audio_filter_plugins().into_iter() {
-                                filter.on_load(&req.url, &req.token).map_err(|e| e.to_string())?;
+                                filter.on_load(&req.url, &req.token)?;
                             }
-                            Ok::<(), String>(())
+                            Ok::<(), PluginError>(())
                         })
-                        .await
-                        .map_err(|e| e.to_string());
+                        .await;
+
+                    // Filter failures are non-fatal: keep the RTC session alive, just
+                    // without the filter enabled.
                     match result {
-                        Err(e) | Ok(Err(e)) => {
-                            log::warn!("error while initializing audio filter: {}", e);
-                            log::error!(
-                                "audio filter cannot be enabled: ensure you are connecting to LiveKit Cloud and that the filter is properly configured"
-                            );
-                            // Skip returning an error here to keep the rtc session alive
-                            // But in this case, the filter isn't enabled in the session.
+                        Ok(Ok(())) => (),
+                        Ok(Err(e)) => {
+                            let hint = match &e {
+                                PluginError::OnLoad(_) => " — ensure you are connecting to LiveKit Cloud and that the filter is configured correctly",
+                                PluginError::Library(_) => " — the filter dylib could not be loaded",
+                                PluginError::NotImplemented(_) => " — the filter dylib is missing a required entry point",
+                            };
+                            log::error!("audio filter disabled, continuing without it: {e}{hint}");
+                        }
+                        Err(join_err) => {
+                            log::error!("audio filter disabled, on_load task panicked: {join_err}");
                         }
-                        Ok(Ok(_)) => (),
                     };
 
                     // Successfully connected to the room

livekit/src/plugin.rs

@@ -32,9 +32,9 @@ use serde_json::json;
 pub enum PluginError {
     #[error("dylib error: {0}")]
     Library(#[from] libloading::Error),
-    #[error("dylib error: {0}")]
+    #[error("unimplemented plugin function: {0}")]
     NotImplemented(String),
-    #[error("on_load failed with error: {0}")]
+    #[error("on_load rejected by plugin (code {0})")]
     OnLoad(i32),
 }