Envqor 即時環境音場偵測用戶操作與 API 手冊

版本日期：2026-05-10

本文件提供 Web 操作、一般裝置 API、檔案上傳分析、即時 WebSocket 串流，以及 Service Backend API 的使用方式。重點是讓操作人員、韌體工程師、第三方後端整合者可以清楚知道自己應該使用哪一組介面。

1. 服務入口

正式環境：

• Web：https://realsound.envqor.com
• API Base URL：https://realsound-api.envqor.com
• Swagger UI：https://realsound-api.envqor.com/docs
• OpenAPI JSON：https://realsound-api.envqor.com/openapi.json
• WebSocket Base：wss://realsound-api.envqor.com

內網測試環境：

• Web：http://192.168.150.221:13000
• API：http://192.168.150.221:13080

注意：瀏覽器啟動麥克風需要 HTTPS 或 localhost。若使用內網 HTTP IP 開啟 Web，檔案上傳通常可用，但 Chrome/Safari 可能會阻擋即時麥克風收音。

2. 使用角色

系統目前分成三種主要使用角色：

3. 一般裝置 API 與 Service API 的差異

這兩組 API 不應混用。一般裝置 API 是給 Web、Firmware、Edge Device 傳音訊與查自己的資料；Service API 是給受信任後端服務做系統整合與裝置管理。

判斷原則：

• 裝置要送音訊：使用一般裝置 WebSocket。
• 使用者要看自己的資料：使用一般裝置查詢 API。
• 後端系統要知道哪些裝置在線、最近有哪些紀錄：使用 Service API。
• 第三方若不是受信任後端，不應取得 Service API Key。

4. Web 操作教學

4.1 開啟 Web

使用瀏覽器開啟：

https://realsound.envqor.com

建議使用 Chrome 或 Safari。第一次開啟時，Web 會檢查 cookie 是否已有 user_id 與 device_id；若沒有，系統會自動產生一組識別資料供 WebSocket 與上傳分析使用。

4.2 即時麥克風偵測

1. 確認 Web 使用 HTTPS 開啟。
2. 在「收音控制」選擇串流模式。
3. 在「輸入裝置」選擇要使用的麥克風，例如系統預設、電腦內建麥克風、AirPods 或外接 USB 麥克風。
4. 若清單只顯示「麥克風 1 / 麥克風 2」或沒有完整名稱，先按「啟用麥克風清單」。
5. 瀏覽器跳出麥克風權限時選擇允許；Web 會短暫取得權限後立刻停止暫時 stream，只用來刷新完整裝置名稱，不會開始正式錄音。
6. 按下「開始」進行正式即時收音。
7. Web 會每 2 秒送出一段音訊給 API 進行 YAMNet 推論。
8. API 每 2 秒回傳 Top-30 聲音事件。
9. API 每 10 秒統計一次場景判定與場景評分結果。
10. 按下「停止」結束收音。

目前 Web 串流模式：

若瀏覽器不支援 Opus WebM/Ogg，請切回 PCM Float32。

4.3 輸入裝置與麥克風清單

Web 會在進入頁面時嘗試讀取瀏覽器可見的 audio input 清單。因為 Chrome/Safari 的隱私限制，尚未授權麥克風前，裝置名稱可能只會顯示為「麥克風 1」、「麥克風 2」，或只顯示系統預設麥克風。

建議操作方式：

1. 進入 Web 後先查看「輸入裝置」選單。
2. 若看到 AirPods、外接麥克風或電腦內建麥克風的完整名稱，可直接選擇。
3. 若名稱不完整，按「啟用麥克風清單」。
4. 授權成功後，Web 會刷新清單並顯示完整裝置名稱。
5. 選擇想使用的輸入裝置後，再按「開始」。

注意事項：

• 「啟用麥克風清單」只用來取得瀏覽器權限與刷新裝置名稱，不會開始正式收音分析。
• 若切換 AirPods、外接 USB 麥克風或手機麥克風後沒有出現在清單，可按輸入裝置旁的重新整理 icon。
• 正在收音時不能切換輸入裝置；請先停止，再切換麥克風後重新開始。
• 不同麥克風增益不同，若場景音量分數明顯偏高或偏低，請再調整 Device dB Offset。

4.4 收音資訊與 Log

收音控制標題旁的 info icon 可查看：

• User ID
• Device ID
• Session ID
• Chunk index
• RMS
• 推論時間
• 即時 Log
• WebSocket 連線與錯誤訊息

這些資訊主要用於除錯，日常操作只需查看右側的場景判定、場景評分結果與 Top-30 偵測結果。

4.5 檔案上傳分析

收音控制下方可上傳 WAV 或 MP3 檔案。

操作方式：

1. 按「選擇檔案」。
2. 選擇 .wav 或 .mp3。
3. 檔案長度上限是 180 秒。
4. 按下分析。
5. API 會每 2 秒切成一筆做 YAMNet 推論。
6. API 每 10 秒統計一次場景摘要。
7. 分析結果會顯示在 Web，並寫入 PostgreSQL。

目前上傳分析會寫入：

• audio_detection_logs：每 2 秒 Top-30、RMS、推論時間與 metadata。
• audio_inference_2s：每 2 秒 YAMNet 分數、embedding、場景規則分數。
• audio_scene_10s：每 10 秒場景摘要。

API 不會保存原始音檔。

4.6 Device 場景設定

Device 場景設定可針對每台裝置調整場景判定規則。

可調整項目包含：

• Device dB Offset：校準裝置音量偏移。
• 場景啟用或停用。
• 場景平均門檻。
• P90 dB 門檻。
• dB 上下限。
• 信心權重。
• 設定版本載入與還原。

建議調整方式：

1. 先確認裝置所在環境，例如住家、室內公共場所、戶外/交通工具、工地/機具。
2. 一次只調整少量參數。
3. 使用 Preview 觀察最近資料的判定差異。
4. 確認後儲存。
5. 每次 Save、Reset、Restore 都會建立版本紀錄，必要時可載入舊版本。

Device dB Offset 是相對校準值，不是經校正儀器認證的 dB(A)/SPL。若不同裝置麥克風增益差異很大，請用現場基準音或分貝計建立 offset。

4.7 本機 AI 推論

右上方「本機 AI 推論」會進入 /local-yamnet。此模式使用瀏覽器本機麥克風與 TensorFlow Lite / TensorFlow.js YAMNet model 在使用者裝置內推論，不把 raw microphone audio 傳到 API。

本機 AI 推論流程：

1. 使用 HTTPS 開啟 Web，按右上方「本機 AI 推論」。
2. 等待模型狀態顯示「已載入」，並看到 YAMNet TFLite 模型 (Self-test: ok)。
3. 選擇輸入裝置；若名稱不完整，先按「啟用麥克風清單」。
4. 按「開始」後，瀏覽器每 2 秒產生一次本機 YAMNet Top-30 推論。
5. Web 只把 Top-30、RMS、dBFS、model runtime、input device label 與推論耗時送到 POST /client-inference/yamnet。
6. API 寫入 PostgreSQL，並每 5 筆 2 秒結果產生一次 10 秒場景摘要。
7. 右側仍會顯示「場景判定」、「Device 場景設定」、「場景評分結果」與「Top-30 偵測結果」。

本機 AI 與伺服器 AI 的差異：

注意：client_submitted 代表 API 驗證資料格式、大小、rate limit 與 user/device 隔離，但無法獨立證明原始麥克風 waveform 內容。因此本機 AI 結果適合用於操作輔助與一般 telemetry；若要做正式稽核，建議使用伺服器 AI 推論或加入額外裝置憑證與抽樣 server-side spot check。

Safari 支援狀態：

• Safari 必須使用 HTTPS 或 localhost，否則無法啟動麥克風。
• Safari 可使用 getUserMedia 與輸入裝置選單，但裝置名稱一樣需要授權後才會完整顯示。
• 若 Safari 無法載入 TFLite/WASM runtime 或 self-test 失敗，頁面會顯示「模型載入失敗，使用本地 fallback adapter」。此時仍可測 UI 與 API 寫入流程，但不代表真正 TFLite YAMNet 成功。
• Chrome 目前是本機 AI 推論主要驗證瀏覽器；Safari 仍需依實機環境記錄模型載入、self-test、連續 2 秒 window 與長時間運作狀態。

5. 一般裝置 HTTP API

5.1 Health Check

curl https://realsound-api.envqor.com/health

成功回應範例：

{
  "status": "ok",
  "yamnet_enabled": true,
  "yamnet_loaded": true,
  "yamnet_load_error": null
}

5.2 查詢最近 2 秒偵測紀錄

curl "https://realsound-api.envqor.com/detections/recent?user_id=test-user&device_id=test-device&limit=20"

用途：

• 查詢每 2 秒推論結果。
• 回傳 Top-30 YAMNet label。
• 回傳 RMS、推論時間、metadata。
• 使用 user_id 與 device_id 做查詢隔離。

5.3 查詢最近 10 秒場景摘要

curl "https://realsound-api.envqor.com/scenes/recent?user_id=test-user&device_id=test-device&limit=20"

用途：

• 查詢每 10 秒統計一次的場景結果。
• 回傳 scene_label、confidence、各場景分數與音量摘要。

目前主要場景：

5.4 查詢裝置清單

curl "https://realsound-api.envqor.com/devices?user_id=test-user"

此 API 適合使用者查詢自己 user_id 底下有紀錄或場景設定的 device。

5.5 檔案上傳分析

WAV 範例：

curl -X POST "https://realsound-api.envqor.com/wav/analyze" \
  -F "user_id=test-user" \
  -F "device_id=test-device" \
  -F "file=@sample.wav;type=audio/wav"

MP3 範例：

curl -X POST "https://realsound-api.envqor.com/wav/analyze" \
  -F "user_id=test-user" \
  -F "device_id=test-device" \
  -F "file=@sample.mp3;type=audio/mpeg"

限制：

• 支援 WAV / MP3。
• 最長 180 秒。
• 每 2 秒一筆推論。
• 每 10 秒一筆場景摘要。
• 結果寫入 PostgreSQL。
• 不保存原始音檔。

回應重點：

• analysis_id：本次離線分析 ID，也作為資料庫 session_id。
• summary：整體統計。
• persistence：寫入資料庫筆數。
• detections_2s：每 2 秒偵測結果。
• scene_summaries_10s：每 10 秒場景摘要。

5.6 Browser 本機 YAMNet 推論結果上傳

POST /client-inference/yamnet 用於 /local-yamnet。Browser 已在本機完成 YAMNet 推論，API 只接收每 2 秒一筆的推論成果，不接收 raw audio。

curl -X POST "https://realsound-api.envqor.com/client-inference/yamnet" \
  -H "Content-Type: application/json" \
  -d @docs/examples/client-inference-yamnet-request.json

用途：

• 寫入 audio_detection_logs 與 audio_inference_2s。
• 每第 5 筆 2 秒推論產生一筆 audio_scene_10s。
• 保留 source_encoding=browser_tflite_yamnet。
• 標示 trust_level=client_submitted。

限制：

• sample_rate 必須是 16000。
• duration_seconds 約 2 秒。
• top_predictions 最多 30 筆。
• request body 目前限制 128 KB。
• API 會做 per user/device rate limit。

6. 一般裝置 WebSocket API

6.1 Raw PCM Float32

Endpoint：

wss://realsound-api.envqor.com/ws/audio?user_id={user_id}&device_id={device_id}

Client flow：

1. 建立 WebSocket 連線。
2. 每次 binary audio frame 前送一個 metadata text frame。
3. 送出 raw Float32Array mono PCM binary frame。
4. Server 回傳 detection JSON。
5. 每 10 秒會在 detection JSON 內帶 scene_10s。

Metadata 範例：

{
  "type": "audio_metadata",
  "metadata": {
    "sample_rate": 48000,
    "duration_seconds": 2.0,
    "user_id": "browser-user-id",
    "device_id": "browser-device-id"
  }
}

Binary frame：

raw little-endian Float32Array mono PCM

6.2 Browser / Device Opus Container Chunk

Endpoint：

wss://realsound-api.envqor.com/ws/audio/opus?user_id={user_id}&device_id={device_id}

適用情境：

• Browser 使用 MediaRecorder 產生 WebM/Opus 或 Ogg/Opus。
• 網路速度較慢，需要比 PCM 更省流量。
• Client 可以產生自包含的 2 秒 Opus container chunk。

Metadata 範例：

{
  "type": "audio_metadata",
  "metadata": {
    "format": "webm",
    "encoding": "opus",
    "duration_seconds": 2.0,
    "user_id": "device-user-id",
    "device_id": "edge-device-id"
  }
}

Binary frame：

one self-contained WebM/Opus or Ogg/Opus chunk

支援格式：

• auto
• webm
• webm_opus
• ogg
• ogg_opus

6.3 Raw 60 ms Opus Packet

Endpoint：

wss://realsound-api.envqor.com/ws/audio/opus-packets?user_id={user_id}&device_id={device_id}

適用情境：

• AMB82-MINI 或其他 Edge Device 已經用 libopus 編碼。
• Firmware 不想實作 WebM/Ogg muxer。
• 想降低資料量與延遲。

規格：

Metadata text frame：

{
  "type": "opus_packet_metadata",
  "metadata": {
    "trace_id": "envqor-rs-001-opus-session-001",
    "codec": "Opus",
    "application": "OPUS_APPLICATION_AUDIO",
    "sample_rate": 16000,
    "channels": 1,
    "channel_layout": "mono",
    "pcm_input_format": "s16le",
    "frame_duration_ms": 60,
    "samples_per_frame": 960,
    "pcm_bytes_per_frame": 1920,
    "target_bitrate_bps": 32000,
    "max_encoded_packet_bytes": 512,
    "client_sent_at": "2026-05-10T12:00:00.000Z",
    "user_id": "dev-user",
    "device_id": "envqor-rs-001"
  }
}

Binary frame：

one WebSocket binary frame = one raw Opus packet
no Ogg page
no WebM cluster
no custom header

Server buffer：

• 每個 60 ms packet 解碼為 960 samples。
• Server 累積到 32000 samples 後跑一次 2 秒推論。
• 34 包會產生 32640 samples，Server 只消耗 32000 samples，剩餘 640 samples 保留到下一個 window。
• chunk_index 依 2 秒 inference window 遞增，不依 packet 遞增。

6.4 Raw Opus Packet Batch

Endpoint：

wss://realsound-api.envqor.com/ws/audio/opus-packet-batches?user_id={user_id}&device_id={device_id}

適用情境：

• Firmware 想減少 WebSocket/TLS 寫入次數。
• 每個 binary frame 打包 1 到 4 個 60 ms Opus packet。
• 仍保留 raw Opus packet 的低 overhead。

Metadata 範例：

{
  "type": "opus_packet_metadata",
  "metadata": {
    "codec": "Opus",
    "application": "OPUS_APPLICATION_AUDIO",
    "sample_rate": 16000,
    "channels": 1,
    "channel_layout": "mono",
    "pcm_input_format": "s16le",
    "frame_duration_ms": 60,
    "samples_per_frame": 960,
    "pcm_bytes_per_frame": 1920,
    "target_bitrate_bps": 32000,
    "max_encoded_packet_bytes": 512,
    "binary_frame_format": "opus_packet_batch_v1",
    "packet_duration_ms": 60,
    "max_packets_per_frame": 4,
    "length_prefix": "uint16_le"
  }
}

Binary frame layout：

uint16_le packet_count

repeat packet_count times:
  uint16_le packet_size_bytes
  uint8[packet_size_bytes] raw Opus packet

範例：

04 00
50 00 ...80 bytes...
4A 00 ...74 bytes...
5C 00 ...92 bytes...
48 00 ...72 bytes...

限制：

• packet_count 最多 4。
• 每個 packet 最大 512 bytes。
• 每個 packet 仍需是 60 ms、960 samples、16 kHz mono Opus。
• Server 逐包 decode，再累積到 2 秒 window 做推論。

6.5 Detection Response

Detection 回應格式會盡量與不同 WebSocket endpoint 保持一致。

{
  "type": "detection",
  "user_id": "test-user",
  "device_id": "test-device",
  "session_id": "uuid",
  "chunk_index": 1,
  "sample_rate": 16000,
  "duration_seconds": 2.0,
  "top_predictions": [
    { "rank": 1, "label": "Speech", "score": 0.912345 }
  ],
  "rms": 0.024,
  "inference_ms": 42.8,
  "scene_10s": {
    "window_sec": 10.0,
    "scene_label": "home_residential",
    "confidence": 0.41
  }
}

scene_10s 只會在累積到 10 秒統計 window 時出現。

7. Device 場景設定 API

7.1 讀取 Device Profile

curl "https://realsound-api.envqor.com/devices/test-device/scene-profile?user_id=test-user"

7.2 儲存 Device Profile

curl -X PUT "https://realsound-api.envqor.com/devices/test-device/scene-profile?user_id=test-user" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_name": "Home Device",
    "is_active": true,
    "config": {
      "calibration": {
        "db_offset": 100,
        "quiet_db_max": 45,
        "loud_db_min": 80
      },
      "scenes": {
        "home_residential": {
          "enabled": true,
          "threshold": 0.35,
          "speech_weight": 0.4,
          "ambience_weight": 2.0
        }
      }
    }
  }'

7.3 Preview

curl -X POST "https://realsound-api.envqor.com/devices/test-device/scene-profile/preview?user_id=test-user"

7.4 Reset

curl -X POST "https://realsound-api.envqor.com/devices/test-device/scene-profile/reset?user_id=test-user"

每次 Save、Reset、Restore 都會建立 revision，方便回到過去版本。

8. Service Backend API

Service API 只給受信任後端使用。所有 /service/* endpoint 都需要：

X-Envqor-Backend-Key: <service-api-key>

不要把 Service API Key 放在：

• Browser frontend
• Mobile app
• Edge device firmware
• 公開文件或 Git repository

8.1 查詢服務狀態

curl -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  "https://realsound-api.envqor.com/service/status"

用途：

• API 是否正常。
• YAMNet 是否載入。
• 裝置數量統計。
• WebSocket session 統計。
• 最近錯誤狀態。

8.2 查詢裝置清單

curl -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  "https://realsound-api.envqor.com/service/devices?user_id=test-user&status=all&limit=100"

status 可用：

• online
• offline
• unknown
• all

8.3 查詢單一裝置狀態

curl -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  "https://realsound-api.envqor.com/service/devices/test-device/status?user_id=test-user"

用途：

• 判斷裝置在線或離線。
• 查看最後收音時間。
• 查看最後推論與場景摘要時間。
• 查看 active session。

8.4 查詢目前 active WebSocket sessions

curl -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  "https://realsound-api.envqor.com/service/sessions/active?user_id=test-user&device_id=test-device"

8.5 查詢近期紀錄

curl -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  "https://realsound-api.envqor.com/service/records/recent?user_id=test-user&device_id=test-device&limit=20"

此 endpoint 適合 Service Backend 做裝置詳情頁，顯示：

• 場景判定（10 秒統計一次）
• 場景評分結果（10 秒統計一次）
• Top-30 偵測結果（最後一筆）

8.6 管理第三方 API Key

Bootstrap key 由環境變數 SERVICE_API_KEYS 提供。正式第三方 key 建議透過資料庫 registry 建立。

列出 API keys：

curl -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  "https://realsound-api.envqor.com/service/api-keys"

建立 API key：

curl -X POST "https://realsound-api.envqor.com/service/api-keys" \
  -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_name": "Partner A",
    "notes": "production backend integration"
  }'

注意：raw API key 只會在建立或 rotate 時回傳一次，資料庫只保存 hash。

停用 API key：

curl -X POST "https://realsound-api.envqor.com/service/api-keys/{key_id}/revoke" \
  -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}"

Rotate API key：

curl -X POST "https://realsound-api.envqor.com/service/api-keys/{key_id}/rotate" \
  -H "X-Envqor-Backend-Key: ${SERVICE_API_KEY}"

9. Swagger 與 WebSocket Contract

Swagger UI：

https://realsound-api.envqor.com/docs

WebSocket 無法完整由 OpenAPI 表達，因此 API 另提供合約查詢：

curl "https://realsound-api.envqor.com/integration/websocket-contract"

建議第三方開發時同時閱讀：

• Swagger UI：HTTP API。
• /integration/websocket-contract：WebSocket metadata、binary format、response JSON。
• 本文件第 6 章：實作注意事項。

10. 資料保存與隱私

目前系統保存的是分析後資料，不保存原始音訊檔案。

會保存：

• user id
• device id
• session id
• trace id
• chunk index
• YAMNet Top-30 predictions
• RMS / calibrated dB summary
• inference duration
• scene scores
• scene label
• YAMNet embedding summary
• metadata JSON

不保存：

• /wav/analyze 上傳的原始音檔。
• WebSocket 即時音訊原始內容。

Service API 可以查詢跨裝置狀態與紀錄，因此必須限制在受信任後端使用。

11. 常見問題排除

11.1 按開始後麥克風啟動失敗

檢查：

• 是否使用 https://realsound.envqor.com。
• 瀏覽器是否允許麥克風權限。
• 是否使用 Chrome 或 Safari。
• 若使用內網 HTTP IP，瀏覽器可能阻擋麥克風。
• 若輸入裝置清單沒有完整名稱，先按「啟用麥克風清單」取得權限後再重新選擇。
• 若剛連上 AirPods 或外接麥克風，按輸入裝置旁的重新整理 icon，或停止收音後重新選擇。

11.2 WebSocket 已關閉

檢查：

• WebSocket URL 是否為 wss://realsound-api.envqor.com/ws/audio 或對應 Opus endpoint。
• API 是否健康：GET /health。
• Nginx 是否支援 WebSocket upgrade。
• user_id 與 device_id 是否存在。

11.3 上傳檔案出現 413

代表 Nginx 或 API 前面的 proxy 限制檔案大小。請調整 Nginx client_max_body_size，並確認檔案長度不超過 180 秒。

11.4 CORS 錯誤

檢查 API CORS_ORIGINS 是否包含 Web 網址：

https://realsound.envqor.com

若上游其實是 413 或 500，瀏覽器也可能先顯示 CORS 錯誤。

11.5 場景判定不符合現場

建議依序檢查：

1. Top-30 偵測結果是否合理。
2. 場景評分結果排序是否符合預期。
3. Device dB Offset 是否過高或過低。
4. Device 場景設定是否曾被修改。
5. 可先 Reset device profile 回預設值再測。
6. 若是道路施工或交通聲容易混淆，請用 Service API 查該 device 最近紀錄，比對 construction_or_machinery 與 outdoor_traffic 的分數差距。

12. 操作檢查表

Web 操作人員：

• 使用 HTTPS Web。
• 確認 browser 允許麥克風。
• 開始收音後查看場景判定是否每 10 秒更新。
• 上傳檔案時確認格式為 WAV/MP3 且長度小於 180 秒。

Firmware / Device 開發者：

• 一般裝置只使用一般裝置 API，不使用 /service/*。
• 固定 user_id 與 device_id。
• 若用 raw Opus，確認 16 kHz mono、60 ms、960 samples、s16le。
• 若用 batch，確認 uint16_le packet_count 與每包 uint16_le packet_size_bytes。
• 收到 detection response 時以 2 秒 chunk_index 為準。

Service Backend 開發者：

• 所有 /service/* request 都帶 X-Envqor-Backend-Key。
• Service Key 只存 server-side。
• 查詢時盡量帶 user_id / device_id 篩選。
• 定期 rotate 第三方 key。
• 不把 Service API 直接暴露給 Browser 或 Device。