🎯 OneComme OSC Router - 使用指南

設定、配置和使用的完整逐步指南

📦 GitHub 儲存庫 ⬇️ 下載最新版本 📖 README 🌐 English 🌐 日本語

📋 概述

OneComme OSC Router 是一個強大的插件,可將 YouTube、Bilibili 和 Niconico 的聊天訊息轉換為 OSC（Open Sound Control）資料串流。本指南將引導您完成設定和使用的每個步驟。

📌 開始之前

請確保您已準備:

  • 已安裝 OneComme 並配置好串流平台帳號
  • 支援 OSC 的應用程式(VRChat、OBS、TouchDesigner 等)
  • 對 OneComme 介面有基本了解

您將學到

📦 安裝

1
下載插件

訪問 GitHub 發布頁面並下載最新版本(v0.8.0 或更新版本)。

顯示下載按鈕的 GitHub 發布頁面
💡 提示: 下載 ZIP 檔案(不是原始碼)。發布版本包含所有相依套件 — 無需執行 npm install！
2
解壓縮到 OneComme 插件目錄

將下載的 ZIP 檔案解壓縮到 OneComme 的插件目錄。資料夾結構應該如下:

OneComme/
└── Plugins/
    └── onecommeOSCrouter/
        ├── plugin.js
        ├── package.json
        ├── web-ui/
        ├── impl/
        ├── tests/
        └── node_modules/

螢幕截圖:檔案總管顯示 OneComme 插件目錄中的插件資料夾

新增螢幕截圖: plugin_folder_structure.png

⚠️ 重要: 資料夾名稱必須為 onecommeOSCrouter(區分大小寫)。使用不同名稱，OneComme 將無法偵測到它。
3
重新啟動 OneComme

完全關閉並重新啟動 OneComme 以偵測新插件。簡單的重新整理無效 — 需要完全重新啟動。

  1. 關閉 OneComme(檔案 → 結束 或 Alt+F4)
  2. 重新啟動 OneComme
  3. 檢查主控台中的插件載入訊息

螢幕截圖: OneComme 主控台顯示插件成功載入訊息

需要手動擷取: console_plugin_loaded.png

4
啟用插件

進入 OneComme 的插件設定並啟用「OneComme OSC Router」:

  1. 開啟 OneComme 設定
  2. 前往插件標籤
  3. 在清單中找到OneComme OSC Router
  4. 勾選啟用核取方塊
  5. 點選套用/儲存

螢幕截圖: 已啟用 OSC Router 的 OneComme 插件設定

新增螢幕截圖: enable_plugin.png

✅ 成功！ 如果一切配置正確，您應該會在 OneComme 主控台中看到插件已啟動的確認訊息。

🚀 首次啟動

5
存取網頁介面

插件啟用後，開啟網頁瀏覽器並前往:

http://localhost:19101

您應該會看到 OneComme OSC Router 控制面板。

首次載入時的網頁介面概述標籤
💡 加入書籤！ 將 http://localhost:19101 儲存為書籤以便快速存取。只要 OneComme 執行且插件已啟用，介面就可以隨時存取。
6
驗證預設配置

插件配有針對 VRChat 最佳化的合理預設值:

設定 預設值 說明
OSC 主機 127.0.0.1 本機(同一台電腦)
OSC 連接埠 19100 標準 VRChat OSC 連接埠
網頁 UI 連接埠 19101 控制面板存取
訊息格式 二進位 標準 OSC 格式

點選設定標籤以檢視並根據需要修改這些設定。

顯示預設配置的設定標籤

🖥️ 網頁介面導覽

網頁介面有四個主要標籤。讓我們逐一探索:

📊 概述標籤

即時監控的儀表板:

螢幕截圖:顯示統計資料和連線狀態的概述標籤

新增螢幕截圖: overview_tab_detailed.png

📜 規則標籤

建立和管理訊息路由規則:

顯示規則清單和管理選項的規則標籤

📋 記錄標籤

即時監控訊息流:

包含訊息歷程和篩選的記錄標籤

⚙️ 設定標籤

配置插件行為:

包含所有配置選項的設定標籤

🎨 建立自訂路由規則

路由規則讓您能將特定類型的訊息發送到不同的 OSC 端點。讓我們逐步建立一個規則。

7
開啟規則建立器
  1. 點選規則標籤
  2. 點選「新增規則」按鈕
  3. 規則建立器模態視窗將出現
規則建立器模態視窗(空白表單)
8
配置基本規則資訊

填寫基本資訊:

  • 規則名稱:描述性名稱(例如:「高額超級留言」)
  • 說明:此規則的作用(選填但建議填寫)
  • 端點:訊息將被發送到的 OSC 位址(例如: /chat/superchats)
  • 已啟用:勾選以立即啟用
已填寫基本資訊的規則建立器
9
新增條件

條件決定哪些訊息符合此規則。範例:路由超過 $20 的超級留言

  1. 點選「新增條件群組」
  2. 選擇平台: YouTube
  3. 選擇訊息類型: superchat
  4. 點選「新增條件」
  5. 設定:
    • 欄位: amount
    • 運算子: greater_than
    • 值: 20
已配置條件的規則建立器
💡 可用運算子:
  • equals - 完全符合
  • not_equals - 不相等
  • contains - 字串包含
  • not_contains - 字串不包含
  • greater_than / less_than - 數值比較
  • regex - 正規表示式符合
  • exists / not_exists - 欄位存在
10
配置欄位對應(選填)

欄位對應讓您自訂 OSC 訊息中包含的資料欄位。如果未指定，將發送所有欄位。

對應範例:

  • username → name
  • message_text → comment
  • donation_amount → amount
  • currency_code → currency

螢幕截圖:包含欄位對應的規則建立器

新增螢幕截圖: rule_builder_mappings.png

11
測試規則

儲存前，使用範例資料測試規則:

  1. 點選「測試規則」按鈕
  2. 測試面板將顯示範例訊息
  3. 查看哪些訊息符合您的規則
  4. 根據需要調整條件

螢幕截圖:顯示符合訊息的規則測試結果

新增螢幕截圖: rule_test_results.png

12
儲存並啟用

對規則滿意後:

  1. 點選「儲存規則」
  2. 規則會出現在規則清單中
  3. 隨時切換開關以啟用/停用
  4. 規則會自動儲存到磁碟
✅ 規則已啟用！ 您的規則現正處理訊息。查看記錄標籤以查看其運作情況。

螢幕截圖:顯示新建立規則的規則清單

新增螢幕截圖: rule_saved_in_list.png

規則範例

以下是一些實用的規則範例助您開始:

規則名稱 目的 條件
僅限 VIP 會員 路由來自頻道會員的訊息 is_member equals true
Bilibili 高額禮物 突顯高價值的 Bilibili 禮物 coins greater_than 100
關鍵字篩選 捕捉特定關鍵字 comment contains \"VRChat\"
封鎖垃圾訊息 過濾垃圾訊息 comment regex \"\\b(spam|bot)\\b\"(NOT 邏輯)

🎮 VRChat 整合

插件已針對 VRChat 進行開箱即用的最佳化。以下是在世界中顯示聊天訊息的方法:

📌 先決條件:
  • 已安裝並執行 VRChat
  • 對 VRChat 的 OSC 系統有基本了解
  • 可以接收 OSC 訊息的虛擬角色或世界

步驟 1:啟用 VRChat OSC

在 VRChat 的動作選單中:

  1. 開啟Options
  2. 前往OSC標籤
  3. 啟用OSC
  4. 如有問題，點選Reset Config

螢幕截圖: VRChat OSC 設定選單

新增螢幕截圖: vrchat_osc_settings.png

步驟 2:驗證連線

插件預設將訊息發送到連接埠 19100(VRChat 的標準連接埠)。驗證方法:

  1. 使用 OneComme 開始串流
  2. 請某人發送聊天訊息
  3. 檢查插件的記錄標籤查看傳出訊息
  4. 在記錄中尋找 /onecomme/youtube/comment(或類似)

螢幕截圖:顯示發送到 VRChat 的訊息的記錄

新增螢幕截圖: logs_vrchat_messages.png

步驟 3:設定虛擬角色/世界參數

要在 VRChat 中顯示訊息，您需要監聽 OSC 位址的虛擬角色參數或世界腳本。

預設 OSC 端點:

💡 虛擬角色創作者: 使用 Udon 或虛擬角色參數來監聽這些 OSC 位址。訊息資料在 OSC 載荷中以 JSON 格式發送。

VRChat 連線疑難排解

如果訊息未在 VRChat 中顯示:

🔧 疑難排解

插件無法載入

症狀:插件未出現在 OneComme 的插件清單中

解決方案:

  • 驗證資料夾名稱正確為 onecommeOSCrouter(區分大小寫)
  • 檢查插件資料夾根目錄中存在 plugin.js
  • 確保存在 node_modules 資料夾(應包含在發布版本中)
  • 嘗試完全重新啟動 OneComme(不只是重新整理)
  • 檢查 OneComme 主控台中的錯誤訊息

網頁介面無法載入

症狀:http://localhost:19101 顯示「無法連線到此網頁」

解決方案:

  • 驗證 OneComme 設定中已啟用插件
  • 檢查是否有其他應用程式正在使用連接埠 19101
  • 嘗試從不同的瀏覽器存取
  • 在 OneComme 主控台中尋找網頁伺服器啟動訊息
  • 檢查 Windows 防火牆設定中被封鎖的連接埠

訊息未到達目標應用程式

症狀:記錄顯示已發送訊息，但目標應用程式未接收

解決方案:

  • 驗證目標應用程式正在正確的連接埠上監聽
  • 確認設定中的 OSC 主機/連接埠符合目標應用程式
  • 嘗試在二進位和字串訊息格式之間切換
  • 檢查防火牆沒有封鎖 UDP 流量
  • 使用 npm run monitor 驗證正在發送 OSC 訊息
  • 變更 OSC 設定後重新啟動目標應用程式

規則未觸發

症狀:已建立規則但訊息未被路由

解決方案:

  • 驗證規則已啟用(切換開關為開啟狀態)
  • 使用規則測試功能驗證條件
  • 檢查條件邏輯(AND vs OR)
  • 驗證欄位名稱符合傳入訊息結構
  • 簡化條件以進行測試(移除除一個條件外的所有條件)
  • 檢查記錄標籤以查看哪些規則正在符合

獲取協助

如果您仍遇到問題:

🚀 進階使用

測試 OSC 訊息

插件在 tests/ 目錄中包含測試工具:

# 執行所有測試
npm test

# 測試配置持久性
npm run test:config

# 測試 OSC 可靠性
npm run test:osc

# 測試訊息格式
npm run test:formats

# 即時 OSC 監控器
npm run monitor

配置檔案

插件設定儲存在本機:

💡 專業提示: 您可以直接編輯 routing-rules.json 以批次建立規則，然後在網頁介面中重新載入。

OSC 訊息格式

訊息以以下結構的 JSON 發送:

{
  "timestamp": "2024-09-20T08:30:01.123Z",
  "service": "youtube",
  "type": "superchat",
  "user": {
    "id": "UC1234567890",
    "name": "StreamerFan123",
    "display_name": "StreamerFan123"
  },
  "message": {
    "content": "很棒的直播！",
    "id": "msg_12345"
  },
  "platform_data": {
    "amount": "5.00",
    "currency": "USD",
    "is_member": true
  },
  "processing": {
    "rule_matched": "High Value Donations",
    "endpoint": "/alerts/bigdonation"
  }
}

REST API

插件在 http://localhost:19101/api/* 公開完整的 REST API:

端點 方法 說明
/api/rules GET 列出所有規則
/api/rules POST 建立新規則
/api/rules/:id PUT 更新規則
/api/rules/:id DELETE 刪除規則
/api/config/full GET 取得配置
/api/logs GET 取得訊息記錄
/api/status GET 系統狀態

效能提示