Trên trang này
SermonWave có một API web đơn giản để bạn có thể bắt đầu và dừng dịch, cũng như chuyển đổi ngôn ngữ, chỉ bằng một lần nhấn nút trên Stream Deck hoặc trong Bitfocus Companion. Bài viết này hướng dẫn cách thiết lập.
Bài viết này dành cho ai#
- Các ban sản xuất điều khiển đèn, trang chiếu và máy quay bằng Elgato Stream Deck.
- Các phòng kỹ thuật dùng Bitfocus Companion để điều khiển nhiều thiết bị từ một bàn điều khiển.
- Bất kỳ ai muốn có một nút "Bắt đầu dịch" mà không cần mở Bảng điều khiển.
Tính năng này hoạt động với mọi loại thiết bị SermonWave: hộp SW1, thiết bị web (trình duyệt) và plugin OBS.
Trước khi bắt đầu#
- Bạn phải là Org Admin (quản trị viên tổ chức). Chỉ quản trị viên tổ chức mới thấy phần cài đặt điều khiển. Xem Người dùng và vai trò.
- Thiết bị bạn muốn điều khiển đã được thiết lập. Xem Chọn loại thiết bị.
- Thời gian dùng thử hoặc gói đang hoạt động. Giống như nút Bắt đầu trên Bảng điều khiển, lệnh bắt đầu từ một nút bấm sẽ bị từ chối khi thời gian dùng thử hoặc gói đăng ký của bạn đã kết thúc. Lệnh Dừng vẫn hoạt động. Xem Các gói và thời gian dùng thử.
- Máy tính chạy ứng dụng Stream Deck hoặc Companion có truy cập Internet.
Bước 1 — Tạo mã điều khiển#
Mã điều khiển (control token) là một khóa bí mật cho phép một nút bấm điều khiển một thiết bị. Mã của thiết bị ở hội trường chính không thể điều khiển thiết bị ở phòng thanh niên.
- Trong Bảng điều khiển, vào Thiết bị và mở thiết bị.
- Mở thẻ Cài đặt và tìm thẻ Điều khiển Stream Deck / API.
- Nhập một cái tên mà sau này bạn sẽ nhận ra, chẳng hạn "Stream Deck phòng kỹ thuật", rồi nhấp Tạo mã.
- Sao chép mã ngay. Mã bắt đầu bằng
swc_và chỉ hiển thị một lần. Thẻ cũng liệt kê các địa chỉ dựng sẵn cho từng thao tác.
Quản lý mã:
- Tối đa 10 mã cho mỗi thiết bị. Hãy tạo mỗi bàn điều khiển một mã để bạn có thể thu hồi một mã mà không làm hỏng các mã khác.
- Thẻ hiển thị Tên, ngày Đã tạo và Lần dùng gần nhất của từng mã.
- Nhấp Thu hồi để vô hiệu hóa một mã. Các nút đang dùng mã đó sẽ ngừng hoạt động ngay lập tức.
Cho phép trong URL. Theo mặc định, mã phải được gửi trong header của yêu cầu. Chỉ bật Cho phép trong URL cho những công cụ không thể gửi header, chẳng hạn một nút "Open website" đơn giản. Khi đó mã được thêm vào địa chỉ dưới dạng ?token=swc_....
Bước 2 — Nắm các địa chỉ#
Mọi địa chỉ đều bắt đầu bằng phần gốc này, trong đó <device_id> là số của thiết bị của bạn:
https://dashboard.sermonwave.com/api/hub/control/<device_id>| Thêm vào phần gốc | Tác dụng |
|---|---|
/start | Bắt đầu dịch ngay (giống nút Bắt đầu trên Bảng điều khiển). |
/stop | Dừng dịch và kết thúc phiên. |
/arm / /disarm | Bật hoặc tắt tự động bắt đầu, để việc dịch tự bắt đầu khi có người nói. |
/toggle | Một nút cho cả hai: dừng nếu thiết bị đang dịch hoặc đang chờ tự động bắt đầu, ngược lại thì bắt đầu. |
/language/toggle/es | Bật hoặc tắt một ngôn ngữ. Ngoài ra còn có /language/add/fr, /language/remove/fr và /language/set/es,fr (đặt toàn bộ danh sách). |
/status | Báo trạng thái ngoại tuyến (offline), rảnh (idle), chờ tự động bắt đầu (armed) hoặc đang ghi (recording), kèm các ngôn ngữ và số người nghe. |
Chi tiết:
- Gửi mã trong một header:
Authorization: Bearer swc_... - Dùng POST khi công cụ của bạn cho phép. Các thao tác cũng chấp nhận GET, dành cho những công cụ chỉ có thể mở một địa chỉ.
- Dùng mã ngôn ngữ mà thiết bị của bạn đã có, chẳng hạn
es(tiếng Tây Ban Nha) hoặcfr(tiếng Pháp). Bạn không thể bỏ ngôn ngữ cuối cùng. - Các thay đổi ngôn ngữ được lưu giống như thay đổi trong thẻ Cài đặt. Nếu thiết bị đang ngoại tuyến, thay đổi sẽ được lưu và áp dụng khi thiết bị kết nối lại.
- Thêm
?format=textđể nhận về một từ duy nhất, chẳng hạnrecording, thay vì JSON.
Bước 3 — Thiết lập Elgato Stream Deck#
- Trong ứng dụng Stream Deck, mở Marketplace và cài plugin miễn phí Web Requests hoặc API Ninja.
- Kéo thao tác HTTP Request của plugin vào một phím.
- Đặt Method là
POSTvà URL là một địa chỉ thao tác, ví dụ.../toggle. - Thêm header. Trong Web Requests, nhập
Authorization: Bearer swc_...vào Headers. Trong API Ninja, dùng{"Authorization":"Bearer swc_..."}. - Nhấn phím trong buổi tập dượt. Phím hiển thị dấu kiểm khi SermonWave đã nhận lệnh, và một cảnh báo khi có lỗi. Kiểm tra lại trong Giám sát trực tiếp.
Tạo mỗi thao tác một phím, ví dụ Bắt đầu, Dừng hoặc "Bật/tắt tiếng Tây Ban Nha" (.../language/toggle/es). Một Multi Action của Stream Deck có thể nối chúng lại với nhau.
Bước 4 — Thiết lập Bitfocus Companion#
- Thêm kết nối Generic: HTTP Requests.
- Trên một nút, thêm thao tác POST. Dùng địa chỉ
.../toggle(hoặc/start,/stop,/language/toggle/es) của bạn. - Trong trường header, nhập
{"Authorization":"Bearer swc_..."}. - Không bắt buộc: thêm phản hồi trạng thái cho nút (xem bên dưới).
Bước 5 — Phản hồi trạng thái trên nút#
Địa chỉ /status trả về state (recording, armed, idle hoặc offline), cho biết thiết bị có đang trực tiếp không, số người nghe và các ngôn ngữ hiện tại.
- Companion: truy vấn
.../statusmỗi 2 đến 5 giây bằng một thao tác GET trên một trigger. Lưu$.statevào một biến tùy chỉnh, rồi tô màu cho nút: đỏ chorecording, vàng hổ phách choarmed, xám chooffline. - Stream Deck: nếu plugin của bạn có thể truy vấn một địa chỉ và hiển thị kết quả trên phím, hãy truy vấn
.../status?format=textmỗi 2 giây hoặc lâu hơn. Nếu không, dấu kiểm hoặc cảnh báo sau mỗi lần nhấn chính là phản hồi của bạn. - Bạn không cần truy vấn ngay sau khi nhấn. Phản hồi của một thao tác đã bao gồm trạng thái mới.
Giới hạn tần suất. Mỗi mã có thể gửi khoảng 30 thao tác và 300 lần kiểm tra trạng thái mỗi phút. Truy vấn mỗi 2 giây dùng khoảng 30 lần. Mỗi thiết bị chỉ chạy một lệnh tại một thời điểm, nên nhấn hai lần liên tiếp cũng không làm thiết bị bật tắt qua lại. Quá nhiều mã sai từ cùng một mạng sẽ bị chặn trong một thời gian.
Ví dụ với curl#
T=swc_your_token_here
BASE=https://dashboard.sermonwave.com/api/hub/control/<device_id>
curl -X POST -H "Authorization: Bearer $T" $BASE/start
curl -X POST -H "Authorization: Bearer $T" $BASE/language/toggle/fr
curl -X POST -H "Authorization: Bearer $T" $BASE/language/set/es,fr
curl -H "Authorization: Bearer $T" "$BASE/status?format=text"
curl -X POST -H "Authorization: Bearer $T" $BASE/stopĐiều khiển cục bộ trong OBS#
Plugin OBS có các nút điều khiển riêng, nhờ đó Stream Deck hoặc Companion có thể chỉ giao tiếp với OBS trong mạng của bạn mà không cần Internet. Chúng xuất hiện trong Settings → Hotkeys của OBS, và plugin cũng trả lời các vendor request của obs-websocket (vendor sermonwave). Để xem danh sách đầy đủ và cách sử dụng, xem Phím tắt và tự động hóa trong OBS.
Khắc phục sự cố#
Đây là các phản hồi bạn có thể nhận được. Cách diễn đạt có thể thay đổi.
| Mã | Ý nghĩa | Cần làm gì |
|---|---|---|
| 200 | Đã xong. Thiết bị đã xác nhận. | Không cần làm gì. |
| 202 | Đã gửi, nhưng thiết bị chưa trả lời. | Kiểm tra Bảng điều khiển. Thường thì thiết bị sẽ cập nhật trong vài giây. |
| 400 | Thiết bị này không có ngôn ngữ đó, hoặc đó là ngôn ngữ cuối cùng. | Dùng một ngôn ngữ mà thiết bị có. Giữ lại ít nhất một ngôn ngữ. |
| 401 | Mã sai, đã bị thu hồi hoặc thuộc về thiết bị khác, hoặc được gửi trong địa chỉ mà chưa bật Cho phép trong URL. | Tạo mã mới cho thiết bị này, hoặc gửi mã trong header. |
| 402 | Thời gian dùng thử hoặc gói đăng ký của bạn đã kết thúc, hoặc một lần thanh toán đã thất bại. | Chọn hoặc gia hạn gói. Lệnh Dừng vẫn hoạt động. Xem Các gói và thời gian dùng thử. |
| 403 | Phần xem trước liên kết trong ứng dụng trò chuyện hoặc mạng xã hội đã cố chạy một thao tác. | Đây là chủ ý. Đừng dán địa chỉ thao tác vào ứng dụng trò chuyện. |
| 409 | Thiết bị đang ngoại tuyến. | Kiểm tra hộp SW1, thẻ trình duyệt của thiết bị web hoặc OBS. Xem Khắc phục sự cố SW1 hoặc Khắc phục sự cố OBS. |
| 429 | Quá nhiều yêu cầu, hoặc một lệnh khác vẫn đang chạy. | Truy vấn thưa hơn. Chờ một chút rồi nhấn một lần. |
| 502 | Thiết bị không thực hiện được (ví dụ: không có đầu vào âm thanh). | Đọc thông báo và khắc phục âm thanh của thiết bị. |
Câu hỏi thường gặp#
Tôi không thấy thẻ Điều khiển Stream Deck / API.#
Chỉ quản trị viên tổ chức mới thấy thẻ này, và nó có thể bị tắt cho một tài khoản. Nếu bạn là quản trị viên mà vẫn không thấy, hãy nhờ bộ phận hỗ trợ bật lên.
Một mã có điều khiển được tất cả thiết bị của tôi không?#
Không. Mỗi mã điều khiển đúng một thiết bị. Hãy tạo mã trên từng thiết bị bạn muốn điều khiển.
Tình nguyện viên không phải quản trị viên có thể tạo mã không?#
Không. Chỉ quản trị viên tổ chức mới có thể tạo hoặc thu hồi mã điều khiển.
Tính năng này có hoạt động với công cụ khác ngoài Stream Deck và Companion không?#
Có. Mọi công cụ có thể gửi yêu cầu web đều dùng được, chẳng hạn bộ điều khiển nhà thông minh hoặc một đoạn script.