🐍
Sora Python SDK 紹介

voluntas
2024/09/29に公開
 時雨堂製品の宣伝記事です
 概要時雨堂の WebRTC SFU Sora で利用できる Sora Python SDK を紹介します。
この記事では映像のみを Sora に送信してその映像をブラウザで視聴してもらうことをターゲットにしています。
具体的な内容はドキュメントを読んでもらえればと思います。

 WebRTC SFU Sora とは時雨堂が 1 から開発し、販売しているパッケージソフトウェアで、Raft ベースの分散型の WebRTC SFU です。
スケールアップ、スケールアウトの両方に対応しています。
Akamai Connected Cloud (Linode) の $ 5 サーバーでもサクサク動きます。

 Sora Python SDK とはSora の C++ SDK をベースにした Python SDK です。 nanobind という技術を利用して C++ SDK を Python から利用できるようにしています。
結局 Python の皮を被った C++ なので、サクサク動作します。

 Sora 買わないと試せないの？いいえ。時雨堂では Sora を検証向けに無料で利用できる Sora Labo というサービスを提供していますので、そちらで試すことができます。 GitHub アカウントがあればすぐ利用できます。
https://sora-labo.shiguredo.app/
この記事では Sora Labo の利用を前提としています。

 Python SDK のセットアップこの記事では uv というツールを使います。

迷える Python パッケージマネージャー界隈の最後の希望です。
インストール方法は以下からどうぞ
Installation | uv

 プロジェクトの作成まずはプロジェクトを作ります。ここでは spam というプロジェクトを作ります。
$ uv init spam
Initialized project `spam` at `/private/tmp/spam`
$ cd spam
$ ls
README.md  hello.py  pyproject.toml

 Sora Python SDK のインストールSora Python SDK をインストールします。

PyPI に登録してあるので、簡単にインストールできます。
uv add sora_sdk

 カメラの映像の取得準備WebRTC で映像を利用する場合、カメラデバイスから映像を取得する必要があります。ブラウザ上での利用であればブラウザがカメラから映像を取得する API を用意してくれていますが、 Python からとなるとそうはいきません。
そのため、 Sora Python SDK では opencv-python を利用して映像を取得します。
opencv-python をインストールをしてください。
uv add opencv-python

 カメラデバイスから映像を取得する例カメラデバイスを取得するのは難しくないのですが、

問題はカメラデバイスから定期的に映像を取得する部分を別途用意する必要があります。
ここではカメラデバイスを取得して、そこから映像を取得するループを作って Python SDK に渡す必要があるという事を理解してもらえれば大丈夫です。
# デバイス ID を 0 を指定してカメラデバイスを取得します
# ここの数字は環境によって変わってきます
video_capture = cv2.VideoCapture(camera_id)

try:
    while True:
        # カメラデバイスからの映像を取得
        success, frame = video_capture.read()
        if not success:
            continue
        # カメラデバイスからの映像を Python SDK に渡す
        # video_source は後から出てきます
        video_source.on_captured(frame)
except KeyboardInterrupt:
    pass
finally:
    # カメラデバイスを解放
    video_capture.release()

 Sora への接続Sora への接続自体はカメラデバイスとの接続を除けばとても簡単ですが、

Sora は基本的に role が sendonly (送信のみ) の場合は音声か映像どちらかを配信する必要があります。
そのため、以下のコードで Sora への接続を行っても切断されてしまいます。
# Sora インスタンスの生成
sora = Sora()

# Sora への接続設定
conn = sora.create_connection(
    # Sora Labo のシグナリング URL を設定します
    signaling_urls=["wss://sora.sora-labo.shiguredo.app/signaling"],
    role="sendonly",
    # Sora Labo でチャネル ID とアクセストークンを作成して指定してください
    # アクセストークンはできるだけ期限を付けることをオススメします
    channel_id="<github-name:str>_<github-id:int>_<channel-name:str>",
    metadata={"access_token": "<access-token:str>"},
)

# Sora へ接続
conn.connect()

 カメラデバイスから取得した映像を Sora Python SDK に渡して Sora へ映像を配信する今までの情報を組み合わせて hello.py を以下のように書き換えてください。
import cv2

import sora_sdk

def main():
    # Sora インスタンスの生成
    sora = sora_sdk.Sora()

    # Python SDK で映像を利用するためには create_video_source で VideoSource インスタンスを生成します
    video_source = sora.create_video_source()

    # Sora への接続設定
    conn = sora.create_connection(
        # sora-labo のシグナリング URL を設定します
        signaling_urls=["wss://sora.sora-labo.shiguredo.app/signaling"],
        role="sendonly",
        # Sora Labo でチャネル ID とアクセストークンを作成して指定してください
        # アクセストークンはできるだけ期限を付けることをオススメします
        channel_id="<github-name:str>_<github-id:int>_<channel-name:str>",
        metadata={"access_token": "<access-token:str>"},
        # 音声は無効にします
        audio=False,
        video=True,
        video_source=video_source,
    )

    # デバイス ID を 0 を指定してカメラデバイスを取得します
    # ここの数字は環境によって変わってきます
    video_capture = cv2.VideoCapture(0)

    # Sora へ接続
    conn.connect()

    try:
        while True:
            # カメラデバイスからの映像を取得
            success, frame = video_capture.read()
            if not success:
                continue
            # カメラデバイスからの映像を Python SDK に渡す
            video_source.on_captured(frame)
    except KeyboardInterrupt:
        pass
    finally:
        # 切断
        conn.disconnect()
        # カメラデバイスを解放
        video_capture.release()

if __name__ == "__main__":
    main()
実行は uv run で行います。
uv run hello.py

 Sora Python SDK からの配信を Sora-DevTools で確認するSora DevTools を利用して確認します。
https://sora-devtools.shiguredo.app/devtools.html?role=recvonly

 設定ChannelId と Metadata と SignalingUrlCandidates を指定します。
channelId: <github-name:str>_<github-id:int>_<channel-name:str>
metadata: {"access_token": "<access-token:str>"}
signalingUrlCandidates: wss://sora.sora-labo.shiguredo.app/signaling

 映像を確認する

 まとめカメラデバイスから映像を取得するところが少し特殊ですがこれで無事 Sora への映像配信ができるようになりました。
もし、もっと色々やってみたいという方は、Sora Python SDK のドキュメントを読んでみてください。
https://sora-python-sdk.shiguredo.jp/
Sora Python SDK と Sora Labo を組み合わせて色々な事ができると思います
時雨堂公式の Discord サーバーもありますので、質問などがあれば気軽に聞いてください。
https://discord.gg/shiguredo
時雨堂ノートPublication
時雨堂製品の宣伝記事です

概要

WebRTC SFU Sora とは

Sora Python SDK とは

Sora 買わないと試せないの？

Python SDK のセットアップ

プロジェクトの作成

Sora Python SDK のインストール

カメラの映像の取得準備

カメラデバイスから映像を取得する例

Sora への接続

カメラデバイスから取得した映像を Sora Python SDK に渡して Sora へ映像を配信する

Sora Python SDK からの配信を Sora-DevTools で確認する

設定

映像を確認する

まとめ

Discussion
