feat: finalize thread-safe FFI and client-local fabric scaffolding

Agent-Logs-Url: https://github.com/Li2CO3ICU/LiPlayerPro/sessions/964e31e0-7332-44d8-ab86-5426c2791402

Co-authored-by: Li2CO3ICU <93815785+Li2CO3ICU@users.noreply.github.com>

Author: Copilot

Cargo.toml

@@ -16,8 +16,18 @@ license = "AGPL-3.0-only"
 name = "liplayerpro_core"
 crate-type = ["rlib", "cdylib"]
 
+[features]
+default = ["tui-app", "native-alsa"]
+tui-app = ["dep:souvlaki", "native-alsa"]
+native-alsa = ["dep:alsa"]
+
+[[bin]]
+name = "LiPlayerPro"
+path = "src/main.rs"
+required-features = ["tui-app"]
+
 [dependencies]
-alsa = "0.7"
+alsa = { version = "0.7", optional = true }
 ringbuf = "0.3"
 crossbeam-channel = "0.5"
 crossterm = "0.27"
@@ -30,6 +40,6 @@ rayon = "1.8"
 unicode-width = "0.1"
 ratatui = "0.26"
 fuzzy-matcher = "0.3"
-souvlaki = "0.7"
+souvlaki = { version = "0.7", optional = true }
 shellexpand = "3.1.0"
 notify = "6.1.1"

fabric-client-local/README.md

@@ -10,7 +10,10 @@
 
 ## 对接步骤
 
-1. 在 Fabric 客户端初始化时加载 native 动态库（`liplayerpro_core`）。
+1. 在 Fabric 客户端初始化时加载 native 动态库：
+   - Linux: `libliplayerpro_core.so`
+   - Windows: `liplayerpro_core.dll`
+   - macOS: `libliplayerpro_core.dylib`
 2. 创建播放器句柄并调用 `liplayer_scan_local_library` 扫描本地音乐目录。
 3. 通过命令/按键/HUD 操作调用：
    - `liplayer_play_track_at`

src/audio_engine.rs

@@ -8,15 +8,20 @@
 // -----------------------------------------------------------------------
 
 #![allow(dead_code, unused_variables)]
+#[cfg(feature = "native-alsa")]
+use alsa::pcm::{Access, Format, HwParams, PCM};
+#[cfg(feature = "native-alsa")]
 use alsa::{Direction, ValueOr};
 use crossbeam_channel::{unbounded, Receiver, Sender};
 use ringbuf::HeapRb;
 use std::io::Read;
 use std::process::{Command, Stdio};
-use std::sync::{Arc, atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering}};
+use std::sync::{
+    atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering},
+    Arc,
+};
 use std::thread;
 use std::time::Duration;
-use alsa::pcm::{PCM, Format, Access, HwParams};
 
 pub enum AudioCmd {
     Play(String),
@@ -90,11 +95,11 @@ impl AudioEngine {
     pub fn get_elapsed_duration(&self) -> Duration {
         let frames = self.current_pos.load(Ordering::Acquire);
         let rate = self.current_sample_rate.load(Ordering::Acquire);
-        
+
         if rate == 0 {
             return Duration::ZERO;
         }
-        
+
         // 🌟 提高精度：先乘后除，防止因为整数除法丢失不足 1 秒的部分
         Duration::from_millis((frames * 1000) / rate as u64)
     }
@@ -131,7 +136,7 @@ impl AudioEngine {
 
                     let pos_tracker_alsa = pos_tracker.clone();
                     let pause_alsa = is_paused.clone();
-                    
+
                     let rb = HeapRb::<i32>::new(2_097_152);
                     let (mut prod, mut cons) = rb.split();
 
@@ -200,7 +205,8 @@ impl AudioEngine {
                         })
                         .unwrap();
 
-                    let alsa_thread = thread::Builder::new()
+                    #[cfg(feature = "native-alsa")]
+                    let output_thread = thread::Builder::new()
                         .name("ALSA_Driver".into())
                         .spawn(move || {
                             while cons.len() < 80_000
@@ -227,24 +233,24 @@ impl AudioEngine {
                                 let mut local_buf = vec![0i32; 16384];
 
                                 while flag_alsa.load(Ordering::Acquire) {
-
-                                    // 🌟 核心休眠逻辑：优雅释放声卡并挂起
                                     if pause_alsa.load(Ordering::Acquire) {
-                                        let _ = pcm.drop(); // 安全丢弃缓存防止爆音
-                                        while pause_alsa.load(Ordering::Acquire) && flag_alsa.load(Ordering::Acquire) {
+                                        let _ = pcm.drop();
+                                        while pause_alsa.load(Ordering::Acquire)
+                                            && flag_alsa.load(Ordering::Acquire)
+                                        {
                                             thread::sleep(Duration::from_millis(50));
                                         }
-                                        let _ = pcm.prepare(); // 取消暂停时重新激活声卡
+                                        let _ = pcm.prepare();
                                         continue;
                                     }
-                                    
+
                                     let avail = cons.len();
                                     if avail >= 2 {
                                         let read_len = std::cmp::min(avail, local_buf.len());
                                         let read_len = read_len - (read_len % 2);
                                         let popped = cons.pop_slice(&mut local_buf[..read_len]);
                                         if popped > 0 {
-                                            if let Err(_) = io.writei(&local_buf[..popped]) {
+                                            if io.writei(&local_buf[..popped]).is_err() {
                                                 let _ = pcm.prepare();
                                             } else {
                                                 pos_tracker_alsa.fetch_add(
@@ -264,8 +270,36 @@ impl AudioEngine {
                         })
                         .unwrap();
 
+                    #[cfg(not(feature = "native-alsa"))]
+                    let output_thread = thread::Builder::new()
+                        .name("NoOp_Output".into())
+                        .spawn(move || {
+                            let mut local_buf = vec![0i32; 16384];
+                            while flag_alsa.load(Ordering::Acquire) {
+                                if pause_alsa.load(Ordering::Acquire) {
+                                    thread::sleep(Duration::from_millis(50));
+                                    continue;
+                                }
+                                let avail = cons.len();
+                                if avail >= 2 {
+                                    let read_len = std::cmp::min(avail, local_buf.len());
+                                    let read_len = read_len - (read_len % 2);
+                                    let popped = cons.pop_slice(&mut local_buf[..read_len]);
+                                    if popped > 0 {
+                                        pos_tracker_alsa
+                                            .fetch_add((popped / 2) as u64, Ordering::Relaxed);
+                                    }
+                                } else if eof_alsa.load(Ordering::Acquire) {
+                                    break;
+                                } else {
+                                    thread::sleep(Duration::from_micros(200));
+                                }
+                            }
+                        })
+                        .unwrap();
+
                     pipeline_threads.push(dec_thread);
-                    pipeline_threads.push(alsa_thread);
+                    pipeline_threads.push(output_thread);
                 }
                 Ok(AudioCmd::Stop) => {
                     play_flag.store(false, Ordering::Release);
@@ -309,6 +343,7 @@ impl AudioEngine {
         }
     }
 
+    #[cfg(feature = "native-alsa")]
     fn negotiate_alsa_rate(device_name: &str, target: u32) -> u32 {
         if let Ok(pcm) = PCM::new(device_name, Direction::Playback, false) {
             if let Ok(hwp) = HwParams::any(&pcm) {
@@ -319,4 +354,9 @@ impl AudioEngine {
         }
         44100
     }
+
+    #[cfg(not(feature = "native-alsa"))]
+    fn negotiate_alsa_rate(_device_name: &str, target: u32) -> u32 {
+        target
+    }
 }

src/ffi.rs

@@ -1,8 +1,10 @@
 use std::ffi::{CStr, CString};
 use std::os::raw::{c_char, c_int, c_ulonglong};
 use std::ptr::null_mut;
+use std::sync::Mutex;
 
 use crate::player_core::{PlayerCore, PlayerState};
+type PlayerHandle = Mutex<PlayerCore>;
 
 const OK: c_int = 0;
 const ERR_NULL: c_int = -1;
@@ -23,7 +25,7 @@ pub extern "C" fn liplayer_create(
     device_name: *const c_char,
     music_dir: *const c_char,
     index_path: *const c_char,
-) -> *mut PlayerCore {
+) -> *mut PlayerHandle {
     let device_name = match cstr_to_string(device_name) {
         Ok(v) => v,
         Err(_) => return null_mut(),
@@ -36,15 +38,15 @@ pub extern "C" fn liplayer_create(
         Ok(v) => v,
         Err(_) => return null_mut(),
     };
-    Box::into_raw(Box::new(PlayerCore::new(
+    Box::into_raw(Box::new(Mutex::new(PlayerCore::new(
         &device_name,
         &music_dir,
         &index_path,
-    )))
+    ))))
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_destroy(handle: *mut PlayerCore) {
+pub extern "C" fn liplayer_destroy(handle: *mut PlayerHandle) {
     if handle.is_null() {
         return;
     }
@@ -56,7 +58,7 @@ pub extern "C" fn liplayer_destroy(handle: *mut PlayerCore) {
 
 #[unsafe(no_mangle)]
 pub extern "C" fn liplayer_scan_local_library(
-    handle: *mut PlayerCore,
+    handle: *mut PlayerHandle,
     music_dir: *const c_char,
 ) -> c_int {
     if handle.is_null() {
@@ -67,30 +69,37 @@ pub extern "C" fn liplayer_scan_local_library(
         Err(code) => return code,
     };
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    core.scan_local_library(&music_dir);
+    let core = unsafe { &*handle };
+    if let Ok(core) = core.lock() {
+        core.scan_local_library(&music_dir);
+    } else {
+        return ERR_OP;
+    }
     OK
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_track_count(handle: *mut PlayerCore) -> usize {
+pub extern "C" fn liplayer_track_count(handle: *mut PlayerHandle) -> usize {
     if handle.is_null() {
         return 0;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    core.list_tracks().len()
+    let core = unsafe { &*handle };
+    core.lock().map(|c| c.list_tracks().len()).unwrap_or(0)
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_list_tracks_json(handle: *mut PlayerCore) -> *mut c_char {
+pub extern "C" fn liplayer_list_tracks_json(handle: *mut PlayerHandle) -> *mut c_char {
     if handle.is_null() {
         return null_mut();
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    let tracks = core.list_tracks();
-    let json = match serde_json::to_string(&tracks.iter().map(|t| &t.path).collect::<Vec<_>>()) {
+    let core = unsafe { &*handle };
+    let tracks = match core.lock() {
+        Ok(c) => c.list_tracks(),
+        Err(_) => return null_mut(),
+    };
+    let json = match serde_json::to_string(&tracks) {
         Ok(v) => v,
         Err(_) => return null_mut(),
     };
@@ -112,69 +121,87 @@ pub extern "C" fn liplayer_string_free(s: *mut c_char) {
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_play_track_at(handle: *mut PlayerCore, index: usize) -> c_int {
+pub extern "C" fn liplayer_play_track_at(handle: *mut PlayerHandle, index: usize) -> c_int {
     if handle.is_null() {
         return ERR_NULL;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    match core.play_track_at(index) {
-        Ok(()) => OK,
+    let core = unsafe { &*handle };
+    match core.lock() {
+        Ok(mut c) => c.play_track_at(index).map(|_| OK).unwrap_or(ERR_OP),
         Err(_) => ERR_OP,
     }
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_stop(handle: *mut PlayerCore) -> c_int {
+pub extern "C" fn liplayer_stop(handle: *mut PlayerHandle) -> c_int {
     if handle.is_null() {
         return ERR_NULL;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    core.stop();
-    OK
+    let core = unsafe { &*handle };
+    if let Ok(mut c) = core.lock() {
+        c.stop();
+        OK
+    } else {
+        ERR_OP
+    }
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_pause(handle: *mut PlayerCore) -> c_int {
+pub extern "C" fn liplayer_pause(handle: *mut PlayerHandle) -> c_int {
     if handle.is_null() {
         return ERR_NULL;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    core.pause();
-    OK
+    let core = unsafe { &*handle };
+    if let Ok(mut c) = core.lock() {
+        c.pause();
+        OK
+    } else {
+        ERR_OP
+    }
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_resume(handle: *mut PlayerCore) -> c_int {
+pub extern "C" fn liplayer_resume(handle: *mut PlayerHandle) -> c_int {
     if handle.is_null() {
         return ERR_NULL;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    core.resume();
-    OK
+    let core = unsafe { &*handle };
+    if let Ok(mut c) = core.lock() {
+        c.resume();
+        OK
+    } else {
+        ERR_OP
+    }
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_elapsed_millis(handle: *mut PlayerCore) -> c_ulonglong {
+pub extern "C" fn liplayer_elapsed_millis(handle: *mut PlayerHandle) -> c_ulonglong {
     if handle.is_null() {
         return 0;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    core.elapsed_millis() as c_ulonglong
+    let core = unsafe { &*handle };
+    core.lock()
+        .map(|c| c.elapsed_millis() as c_ulonglong)
+        .unwrap_or(0)
 }
 
 #[unsafe(no_mangle)]
-pub extern "C" fn liplayer_state(handle: *mut PlayerCore) -> c_int {
+pub extern "C" fn liplayer_state(handle: *mut PlayerHandle) -> c_int {
     if handle.is_null() {
         return ERR_NULL;
     }
     // SAFETY: handle is checked for null and points to a valid PlayerCore by API contract.
-    let core = unsafe { &mut *handle };
-    match core.state() {
+    let core = unsafe { &*handle };
+    let state = match core.lock() {
+        Ok(c) => c.state(),
+        Err(_) => return ERR_OP,
+    };
+    match state {
         PlayerState::Idle => 0,
         PlayerState::Playing => 1,
         PlayerState::Paused => 2,