API リファレンス - Hylable Discussion

Hylable Discussion を操作するソフトウェアを開発するためのモジュールです。最初に HDClient クラスのインスタンスを作成して、そのメソッドを実行することで操作を行います。

データは、以下の dataclass で定義されるクラスのオブジェクトとして扱います

コース: Course
ディスカッション: Discussion
メンバー: Member
レコーダー: Recorder

class hylable.hd.HDClient(profile_name: str = 'default')

Hylable Discussion との通信を行うクラス

add_course(course: Course) → None

コースを追加する関数

パラメータ:: course (Course) -- 追加するコース

サンプル

>>> client = HDClient()
>>> course = Course({
>>>     "name": "test course",
>>>     "year": 2021,
>>>     "comment": "test course"
>>> })
>>> client.add_course(course)
>>> # 追加したコースを取得
>>> course = [
        c for c in client.get_courses()
        if c.name == "test course"
    ][0]

add_members(members: list[Member]) → list[Member]

組織にメンバーを追加する関数

戻り値:: メンバーのリスト
戻り値の型:: list[Members]

サンプル

>>> client = HDClient()
>>> members_in = [
        Member(name="メンバー1"),
        Member(name="メンバー2"),
        Member(name="メンバー3")
    ]
>>> members_out = client.add_members(members_in)

create_discussion(course_id: str, recorder: Recorder, topic: str = 'From Hylable SDK', recordedAt: datetime | None = None, options: dict = {}) → Discussion

ディスカッションを作成する関数

作成したディスカッションに対する録音は start_recording() メソッドで行う

パラメータ:

course_id (str) -- ディスカッションを作成するコースのID
recorder (Recorder) -- 録音に使うレコーダー
topic (str) -- トピック
recordedAt (datetime or None) -- 録音開始時刻。デフォルト(None)の場合は現在時刻
options (dict) -- オプション設定

戻り値:

作成したディスカッション

戻り値の型:

Discussion

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> recorders = client.get_recorders()
>>> discussion = client.create_discussion(courses[0].id, recorders[0])

del_course(course: Course) → None

コースを削除する関数

パラメータ:: course (Course) -- 削除するコースのオブジェクト

サンプル

>>> client = HDClient()
>>> client.del_course(course.id)

del_discussion(discussion: Discussion) → None

特定のディスカッションを削除する関数

パラメータ:: discussion (Discussion) -- 削除するディスカッションのオブジェクト

サンプル

>>> client = HDClient()
>>> discussion_obj = Discussion("ID OF THE DISCUSSION")
>>> client.get_discussions(discussion_obj)

del_member(member: Member) → None

メンバーを削除する関数

パラメータ:: member (Member) -- 削除するメンバーのオブジェクト

サンプル

>>> client = HDClient()
>>> member = [
        m for m in client.get_members()
        if m.name == "MEMBER_TO_DELETE"
    ][0]
>>> client.del_member(member.id)

get_asr(discussion: Discussion) → list[dict]

音声認識結果を取得する関数

パラメータ:: discussion (Discussion) -- 音声認識結果を得る Discussion ID

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()[0]
>>> discussion = client.get_discussions(courses[0])[0]
>>> client.get_asr(discussion)

get_available_discussion_reports() → dict

ダウンロード可能なレポートの一覧を取得する関数。 get_discussion_report() で使用する。

戻り値:

ダウンロード可能なレポートの一覧。各リストの要素は以下の通り。

name (str): レポートの名前
id (str): レポートのフォーマットID
lang (str): レポートの出力言語

戻り値の型:

list[dict]

サンプル

>>> client = HDClient()
>>> reports = client.get_available_discussion_reports()

get_course(course_id: str) → Course

特定のコースの詳細を得る関数

パラメータ:: course_id (str) -- コースのID
戻り値:: ID に対応するコースのオブジェクト
戻り値の型:: Course
例外:: DataNotFoundError -- 指定されたコースIDがない時

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> course = client.get_course(courses[0].id)

get_courses() → list[Course]

すべてのコースを得る関数

戻り値:: コースのリスト
戻り値の型:: list[Course]

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()

get_discussion(discussion_id: str) → Discussion

特定のディスカッションの詳細を得る関数

パラメータ:: discussion_id (str) -- ディスカッションのID
戻り値:: discussion_id に対応するディスカッションのオブジェクト
戻り値の型:: Discussion
例外:: DataNotFoundError -- 指定されたディスカッションIDがない時

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> discussions = client.get_discussions(courses[0].id)
>>> discussion = client.get_discussion(discussions[0].id)

get_discussion_report(discussion: Discussion, report_format_id: str, lang: str = 'ja') → bytes

ディスカッションの PDF レポートを取得する関数

パラメータ:

discussion (Discussion) -- レポートを取得するディスカッションオブジェクト
report_format_id (str) -- レポートのフォーマットID
lang (str) -- レポートの出力言語

戻り値:

PDF レポートのバイナリデータ

戻り値の型:

bytes

例外:

ValueError -- report_format_id が利用可能でないとき

サンプル

>>> client = HDClient()
>>> course = client.get_courses()[0]
>>> discussion = client.get_discussions(course.id)[0]
>>> format = client.get_available_discussion_reports()[0]
>>> report_content = client.get_discussion_report(discussion, format["id"], format["lang"])
>>> pathlib.Path("report.pdf").write_bytes(report_content)

get_discussions(course_id: str) → list[Discussion]

指定されたコースにある全てのディスカッションを得る関数

戻り値:: ディスカッションのリスト
戻り値の型:: list[Discussion]

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> discussions = client.get_discussions(courses[0].id)

get_member(member_id: str) → Member

特定のメンバーの詳細を得る関数

パラメータ:: member_id (str) -- メンバーのID
戻り値:: member_id に対応するメンバーのオブジェクト
戻り値の型:: Member
例外:: DataNotFoundError -- 指定されたメンバーIDがない時

サンプル

>>> client = HDClient()
>>> members = client.get_members()
>>> member = client.get_member(members[0].id)

get_members() → list[Member]

すべてのメンバーリストを得る関数

戻り値:: メンバーのリスト
戻り値の型:: list[Member]

サンプル

>>> client = HDClient()
>>> members = client.get_members()

get_mp3(discussion: Discussion, filelike=None) → bytes

指定されたディスカッションの音声データを mp3 で詳細を得る関数

パラメータ:

discussion (Discussion) -- 音声データを得るディスカッションのオブジェクト
filelike (str or None) -- ファイルを保存するパス。デフォルトでは保存しない

戻り値:

mp3 を表すデータ

戻り値の型:

bytes

例外:

DataNotFoundError -- 指定されたディスカッションIDに mp3 がないとき

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> discussions = client.get_discussions(courses[0].id)
>>> data = client.get_mp3(discussions[0].id, 'audio.mp3')
>>> pathlib.Path('audio2.mp3').write_bytes(data)

get_recorder(recorder_id: str) → Recorder

特定のレコーダーの詳細を得る関数

パラメータ:: recorder_id (str) -- レコーダーのID
戻り値:: recorder_id に対応するレコーダーのオブジェクト
戻り値の型:: Recorder
例外:: DataNotFoundError -- 指定されたレコーダーIDがない時

サンプル

>>> client = HDClient()
>>> recorder_id = "ID OF THE RECORDER"
>>> recorder = client.get_recorder(recorder_id)

get_recorders() → list[Recorder]

すべてのレコーダーを得る関数

戻り値:: レコーダーのリスト
戻り値の型:: list[Recorder]

サンプル

>>> client = HDClient()
>>> members = client.get_recorders()

reboot_recorder(recorder: Recorder)

レコーダーを再起動する関数

パラメータ:: recorder (Recorder) -- 再起動するレコーダー

サンプル

>>> client = HDClient()
>>> recorders = client.get_recorders()
>>> client.reboot_recorder(recorders[0])

shutdown_recorder(recorder: Recorder)

レコーダーを再起動する関数

パラメータ:: recorder (Recorder) -- 再起動するレコーダー

サンプル

>>> client = HDClient()
>>> recorders = client.get_recorders()
>>> client.shutdown_recorder(recorders[0])

speak_recorder(recorders: list[Recorder], content: str, language: str = 'ja_JP') → None

レコーダーから音声合成を行う関数

パラメータ:

recorder (Recorder) -- 音声合成を行うレコーダー
content (str) -- 音声の内容
language (str) -- 言語 (ja_JP or en_US)

サンプル

>>> client = HDClient()
>>> recorders = client.get_recorders()
>>> client.speak_recorder(recorders[0], "こんにちは")

start_recording(discussion: Discussion) → None

ディスカッションの録音を開始する関数

create_discussion() で作成したディスカッションの録音を行う。録音に使用するレコーダーは引数に与えられた discussion オブジェクトの recorder プロパティで指定されている。

パラメータ:: discussion (Discussion) -- 録音を行うディスカッションのオブジェクト

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> recorders = client.get_recorders()
>>> discussion = client.create_discussion(courses[0].id, recorders[0])
>>> client.start_recording(discussion)

stop_recording(recorders: list[Recorder])

レコーダーの録音を停止する関数

録音中のレコーダーの録音を停止する関数。

パラメータ:: recorders (list[Recorder]) -- リストで与えられたすべてのレコーダーの録音を停止できる。

サンプル

>>> client = HDClient()
>>> courses = client.get_courses()
>>> recorders = client.get_recorders()
>>> discussion = client.create_discussion(courses[0].id, recorders[0])
>>> client.start_recording(discussion)
>>> time.sleep(10)
>>> client.stop_recording(recorders[0])

update_course(course: Course) → None

コースを更新する関数

パラメータ:: course (Course) -- 更新するコースのオブジェクト

サンプル

>>> client = HDClient()
>>> course = client.get_course(course_id)
>>> course.name = "new name"
>>> client.update_course(course)

update_discussion(discussion: Discussion) → None

ディスカッションを更新する関数

パラメータ:: discussion (Discussion) -- 更新するディスカッションのオブジェクト

サンプル

>>> client = HDClient()
>>> discussion = client.get_discussion(discussion_id)
>>> discussion.title = "new title"
>>> discussion.members[0]['position'] = 0
>>> client.update_discussion(discussion)

update_member(member: Member, password: str = '') → None

メンバーを更新する関数

パラメータ:

member (Member) -- 更新するメンバーのオブジェクト
password (str) -- メンバーのアカウントのパスワード。新規作成するときのみ必要。

サンプル

>>> client = HDClient()
>>> member = client.get_member(member_id)
>>> print("メンバー名を変更する")
>>> member.name = "new name"
>>> client.update_member(member)
>>>
>>> print("メンバーのアカウントを作成する")
>>> member.account = {
        "name": "my login name",
        "type": "viewer",  # アカウントの権限
    }
>>> client.update_member(member, password="my password")

watch_discussion(callback: ~typing.Callable[[~hylable.hd.Discussion], None] = <function HDClient.<lambda>>) → None

ディスカッションを監視する関数

ディスカッションの作成や変更、削除検知すると、コールバック関数 callback が呼び出される。 callback の引数は Discussion 型のオブジェクト。関数内で client.is_alive を False にすると監視を終了できる。

パラメータ:: callback (Callable[[Discussion], None]) -- コールバック関数

サンプル

>>> client = HDClient()
>>> def callback(discussion):
>>>     print(discussion)
>>> client.watch_discussion(callback)

watch_recorder(callback: ~typing.Callable[[~hylable.hd.Recorder], None] = <function HDClient.<lambda>>) → None

レコーダーの変更を監視する関数

レコーダーの変更を監視する関数。組織に登録されているレコーダーの変更を検知すると、コールバック関数 callback が呼び出される。 callback の引数は Recorder 型のオブジェクト。関数内で client.is_alive を False にすると監視を終了できる。

パラメータ:

course (Course) -- 監視するコース
callback (Callable[[Discussion], None]) -- コールバック関数

サンプル

>>> client = HDClient()
>>> def callback(recorder):
>>>     print(recorder)
>>> client.watch_recorder(callback)

Hylable Discussion を操作するソフトウェアを開発するためのモジュールです。最初に HDClient クラスのインスタンスを作成して、そのメソッドを実行することで操作を行います。

データは、以下の dataclass で定義されるクラスのオブジェクトとして扱います

コース: Course
ディスカッション: Discussion
メンバー: Member
レコーダー: Recorder

class hylable.hd.Course(rawdata: dict = <factory>, id: str = '', orgid: str = '', comment: str = '', name: str = '', year: int = 0, members: list[~hylable.hd.Member] = <factory>, group: list = <factory>)

ベースクラス: BaseDataModel

コースを表す dataclass

id

crs_ から始まるコースの ID

Type:: str

orgid

org_ から始まる組織の ID

Type:: str

comment

コースに対するコメント

Type:: str

name

コースの名前

Type:: str

year

コースの実施年

Type:: int

members

コースに登録されているメンバーのリスト

Type:: List[Member]

group

レコーダーの座席情報のリスト

Type:: List[dict]

class hylable.hd.Discussion(rawdata: dict = <factory>, id: str = '', course_id: str = '', orgid: str = '', recordedAt: ~datetime.datetime | None = None, topic: str = '', comment: str = '', duration_sec: int = 0, progress: int = 0, status: str = '', recorder: ~hylable.hd.Recorder | None = None, group_name: str = '', members: list[dict[str, int | float | ~hylable.hd.Member]] = <factory>, frames: dict = <factory>, stats: dict = <factory>, annotations: list = <factory>, dest: str = <factory>, _group: str = <factory>, options: dict = <factory>)

ベースクラス: BaseDataModel

ディスカッションを表す dataclass

id

UUID で表されるディスカッションの ID

Type:: str

course_id

crs_ から始まるこのディスカッションが所属するコースのID

Type:: str

orgid

org_ から始まる組織の ID

Type:: str

recordedAt

このディスカッションの録音が開始された時刻。タイムゾーンは UTC。

Type:: Date

topic

このディスカッションのトピック

Type:: str

comment

このディスカッションに対するコメント

Type:: str

duration_sec

このディスカッションの長さ (単位は秒)

Type:: int

progress

このディスカッションの分析の進捗状況 (0から100まで)

Type:: int

status

このディスカッションの状態。以下のいずれかの値を取る。

created	ディスカッションが作成完了
recording	録音中
uploading	アップロード中
completed	分析が完了している
error	エラーが発生した

Type:: str

recorder

このディスカッションの収録に使われたレコーダー

Type:: Recorder

group_name

このディスカッションを行ったグループ名

Type:: str

members

このディスカッションに参加したメンバーのリストリストの各要素は、ディクショナリになっている。各ディクショナリはメンバーの位置をあらわす position と、メンバー情報自体を表す member のプロパティをもつ。 {'position': -30, 'member': 該当するメンバーのオブジェクト}

Type:: list[dict]

frames

このディスカッションのフレームごとの分析結果。dictionary の key は以下の通り。

activity (list): メンバーごとの発話量の時間変化を表すリストのリスト。リストのサイズはフレーム数 x メンバー数。フレームは 5秒ごとに計算される。それぞれの数値は 0 から 1 までの値をとり、当該フレーム内における、そのメンバーの発話量の割合を表す。値の順番は members の並びと同じ。

Type:: dict

stats

このディスカッションの分析結果の統計データ。 dictionary の key は以下の通り。

activity (list): メンバーごとの発話量のリスト。値の順番は members の並びと同じ。最小値0、最大値1で、値が大きいほど発話量が多い。
enhancement (list): メンバーごとの盛り上げ量のリスト。値の順番は members の並びと同じ。最小値0、最大値1で、値が大きいほどそのメンバーの発話後に他のメンバーの発話量が増加したことを表す。 0.5 のときは変化なし。0.5 以下のときは盛り下がったことを、 0.5 より大きいときは盛り上がったことを表す。
overlap (list): メンバーごとの重なり量のリスト。値の順番は members の並びと同じ。最小値0、最大値1で、値が大きいほどそのメンバーと他のメンバーの発話の重複が多いことを表す。
tlot_ms (list): メンバーごとの総発話時間のリスト。値の順番は members の並びと同じ。単位はミリ秒。
duration_per_azimuth (dict): 方向ごとの音声検出時間。dict には azimuth と duration のプロパティがある。 azimuth と duration はそれぞれ同じ長さの numpy.array で、それぞれ対応している。方位角ごとに、その方向から到来した音声の長さを表す (単位はミリ秒)。
overlap_matrix (list): メンバーごとの重なり量を表すリストのリスト。二次元正方行列で、行列のサイズはメンバー数と同じ。行列の (i, j) 要素は、メンバー i からメンバー j へ重なった量を表す。
turntake_matrix (list): メンバーごとのターンテイクを表すリストのリスト。二次元正方行列で、行列のサイズはメンバー数と同じ。行列の (i, j) 要素は、メンバー i の後にメンバー j が発言した回数表す。

Type:: dict

annotations

このディスカッションに対するアノテーション。形式は以下の通りで。開始と終了時刻はミリ秒。 {'begin': 開始時刻, 'end': 終了時刻, 'label': アノテーションの内容}

Type:: list[dict]

class hylable.hd.Member(rawdata: dict = <factory>, id: str = '', orgid: str = '', name: str = '', course_ids: list = <factory>, account: dict = <factory>)

ベースクラス: BaseDataModel

メンバーを表す dataclass

id

mem_ から始まるメンバーの ID

Type:: str

orgid

org_ から始まる組織の ID

Type:: str

name

メンバーの名前

Type:: str

course_ids

このメンバーが登録されているコースIDのリスト

Type:: list[str]

account

このメンバーのアカウント情報

Type:: dict

class hylable.hd.Recorder(rawdata: dict = <factory>, id: str = '', name: str = '', orgid: str = '', type: str = '', assign: str = '', connected: bool = False, status: str = '', version: str = '')

ベースクラス: BaseDataModel

レコーダーを表す dataclass

id

レコーダーのID

Type:: str

name

レコーダーの名前

Type:: str

orgid

org_ から始まる組織の ID

Type:: str

type

レコーダーのタイプ

Type:: str

assign

レコーダーが登録された対象のID。 Hylable Discussion であればコースIDが、 Bamiel であればフィールドIDが入る。

Type:: str

connected

レコーダーがサーバーに接続されているかを表すフラグ

Type:: bool

status

レコーダーの状態

Type:: str

version

レコーダーのファームウェアのバージョン

Type:: str