> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/hosted-experience/hosted-experience-methods-2.md).

# メソッド

インスタンスを作成したら、それと対話して動的に動作を制御できます。以下のメソッドは、インスタンス（例：`uneeqInstance`）で利用可能です。

オプションについて詳しく知りたい場合は、設定オプションをご覧ください。

```jsx
// コードスニペットサンプルをそのまま利用している場合
const uneeq = new Uneeq(uneeqOptions)
// uneeq で各種メソッドを呼び出せます。例：
// uneeq.cameraAnchorHorizontal('center', 500)

//　例としてuneeqInstanceと設定している場合
const uneeqInstance = new Uneeq(options)
// uneeqInstance で各種メソッドを呼び出せます。例：
// uneeqInstance.cameraAnchorHorizontal('center', 500)
```

### init()

オプションを検証し、メッセージイベントハンドラを設定することで、インスタンスを初期化します。

```jsx
uneeqInstance.init()
```

### cameraAnchorHorizontal(`position`, `duration`)

カメラに指定されたアンカーポジションへの移動を要求します。

**パラメータ**

* `position` (string): 希望するカメラのアンカーポジション。`left` `right` `center`
* `duration` (number): カメラ移動の所要時間をミリ秒で指定します。

```jsx
uneeqInstance.cameraAnchorHorizontal('center', 500);
```

### cameraAnchorDistance(`position`, `duration`)

カメラに指定されたアンカーポジションへの移動を要求します。

**パラメータ**

* `position` (string): 希望するカメラのアンカーポジション。 `close_up` `loose_close_up` `tight_medium_shot` `medium_shot` `medium_full_shot` `full_shot`
* `duration` (number): カメラ移動の所要時間をミリ秒で指定します。

```jsx
uneeqInstance.cameraAnchorDistance('close_up', 500);
```

### changeAvatar(`avatarId`)

デジタルヒューマンのアバター（スキン）を変更します。セッション中に別のアバターに切り替える場合に使用します。

**パラメータ**

* `avatarId` (string): 切り替え先のアバターID。

```jsx
uneeqInstance.changeAvatar('avatar-id-here');
```

### loadBackground(`url`)

現在のセッションを終了せずに、デジタルヒューマンのシーンに新しい背景画像を実行時に読み込みます。

**パラメータ**

* `url` (string): 背景画像の HTTPS URL。`https://res.cloudinary.com/<your_cloud_name>/<path>` 形式の Cloudinary 配信 URL である必要があります。このパターンに一致しない URL は、レンダラー側で警告なく破棄されます。

```jsx
uneeqInstance.loadBackground('https://res.cloudinary.com/your_cloud_name/image/upload/v1234567890/backgrounds/lobby.jpg');
```

### chatPrompt(`prompt`,`addClosedCaption`)

デジタルヒューマンにチャットプロンプトを送信します。

**パラメータ**

* `prompt` (string): チャットプロンプトメッセージ。
* `addClosedCaption`(boolean): プロンプトメッセージをクローズドキャプションに追加するかどうか。 デフォルト: `false`。

```jsx
uneeqInstance.chatPrompt('こんにちは、お名前を教えてください。', true);
```

### speak(`speech`)

デジタルヒューマンに発話リクエストを送信します。これは進行中のスピーチを中断します。複数または重複した発話リクエストを送信しても、それらのリクエストがキューに入れられることはありません。

**パラメータ**

* `speech` (string): デジタルヒューマンが話す発話文。

```jsx
uneeqInstance.speak('こんにちは、デジタルヒューマンのソフィーです。お話ししましょう。');
```

### openAudioStream()

音声ストリームを開始します。外部の音声ソースからデジタルヒューマンに音声を送信するためのストリームを確立します。`speakAudio()` で音声パケットを送信する前に呼び出す必要があります。

```jsx
uneeqInstance.openAudioStream();
```

### closeAudioStream()

音声ストリームを終了します。`openAudioStream()` で開始した音声ストリームを閉じます。

```jsx
uneeqInstance.closeAudioStream();
```

### speakAudio(`audio`)

デジタルヒューマンに音声パケットを送信して発話させます。事前に `openAudioStream()` でストリームを開始しておく必要があります。

**パラメータ**

* `audio`: 送信する音声データ。

```jsx
uneeqInstance.openAudioStream();
uneeqInstance.speakAudio(audioData);
uneeqInstance.closeAudioStream();
```

### interruptAudioStream()

現在進行中の `speakAudio` リクエストを中断します。音声ストリーム経由での発話を即座に停止させる場合に使用します。

```jsx
uneeqInstance.interruptAudioStream();
```

### enableMicrophone()

ユーザーのマイクを有効にして音声録音を行います。

```jsx
uneeqInstance.enableMicrophone();
```

### endSession()

現在のセッションを終了します。

```jsx
uneeqInstance.endSession();
```

### pauseSpeechRecognition()

音声認識処理を一時停止します。これはユーザーのマイクをミュートすることに相当します。

```jsx
uneeqInstance.pauseSpeechRecognition();
```

### resumeSpeechRecognition()

音声認識処理を再開します。これはユーザーのマイクをミュート解除することに相当します。

```jsx
uneeqInstance.resumeSpeechRecognition();
```

### setCustomPromptMetadata(`customMetadata`)

チャットプロンプトのカスタムメタデータを設定します。

**パラメータ**

* `customMetadata` (Object): チャット用のカスタムメタデータ。

```jsx
uneeqInstance.setCustomPromptMetadata({"key":"value"});
uneeqInstance.setCustomPromptMetadata({"name":"john"})
```

### setLayoutMode(`layoutMode`)

インターフェースのレイアウトモードを設定します。

**パラメータ**

* `layoutMode` (string): `overlay` `fullScreen` `contained`

```jsx
uneeqInstance.setLayoutMode('fullScreen');
```

### **setWebRtcStatsEnabled(`enableMessages: boolean`, `enableLogs: boolean`)**

ビデオや音声の品質問題を診断するために、WebRTC のロギングをオン／オフにできます。enableLogs を有効にするとブラウザのコンソールに出力されます。これらのメッセージをプログラムで処理したい場合は `enableMessages` を有効にすると、メッセージがページに渡されて処理できるようになります。

`enableMessages` を有効にすると、ページは `uneeqMessageType: "WebRtcStats"` というキー/値ペアを含むメッセージを受け取ります。

```jsx
uneeqInstance.setWebRtcStatsEnabled(true, true);
```

### setNetworkIndicatorEnabled(`config`)

ネットワーク品質インジケーターの表示／非表示を切り替えます。設定オブジェクトを渡すと監視を開始し、引数なしで呼び出すと無効化します。設定オプションの [`networkIndicator`](/dev/hosted-experience/hosted-experience-configuration-options.md#networkindicator) を使うと、セッション開始時に自動表示することもできます。

**パラメータ**

* `config` (Object, 任意): 指定するとインジケーターを有効化、省略すると無効化します。
  * `visibility` (string): 表示タイミング。`'always'` / `'when-degraded'` / `'hidden'`。デフォルト: `'when-degraded'`
  * `position` (string): 映像コンテナ内の四隅位置。`'top-left'` / `'top-right'` / `'bottom-left'` / `'bottom-right'`。デフォルト: `'top-right'`
  * `popupTrigger` (string): 詳細パネルの表示トリガー。`'click'` / `'hover'` / `'none'`。デフォルト: `'click'`
  * `collectionIntervalMs` (number): WebRTC 統計を収集する間隔（ミリ秒）。デフォルト: `3000`
  * `expectedFrameRate` (number): 映像 MOS の算出に使う想定ソースフレームレート。デフォルト: `30`

```jsx
// デフォルトで有効化
uneeqInstance.setNetworkIndicatorEnabled({});

// カスタム設定で有効化
uneeqInstance.setNetworkIndicatorEnabled({
  visibility: 'always',
  position: 'bottom-left',
  popupTrigger: 'hover',
  collectionIntervalMs: 5000,
  expectedFrameRate: 25
});

// 無効化
uneeqInstance.setNetworkIndicatorEnabled();
```

### stopSpeaking()

デジタルヒューマンに発話を停止するよう指示します。

```jsx
uneeqInstance.stopSpeaking();
```

### unmuteDigitalHuman()

ブラウザの自動再生ポリシーによってミュートされている場合、デジタルヒューマンのミュートを解除します。

```jsx
uneeqInstance.unmuteDigitalHuman();
```

### muteDigitalHuman()

デジタルヒューマンをミュートします。音声を再び受け取るには、`unmuteDigitalHuman()`を呼び出す必要があります。このミュート状態の画面上のインジケーターはありません。

```jsx
uneeqInstance.muteDigitalHuman();
```

### updateDisplayContent(`htmlContent`)

コンテンツウィンドウに表示するHTMLコンテンツを設定します。

**パラメータ**

* `htmlContent` (string): 表示するHTMLコンテンツ。

```jsx
uneeqInstance.updateDisplayContent('<p>New Content</p>');
```

* `null` : HTMLコンテンツを非表示にする。

```jsx
uneeqInstance.updateDisplayContent(null);
```

### setShowClosedCaptions(`show`)

クローズドキャプションを表示するかどうかを設定します。

**パラメータ**

`show` (boolean): クローズドキャプションを表示する場合は`true`、そうでない場合は`false`。

```jsx
uneeqInstance.setShowClosedCaptions(true);
```

### setShowUserInputInterface(`show`)

ユーザー入力インターフェース（テキスト/音声入力UI）を表示するかどうかを設定します。

**パラメータ**

`show` (boolean): ユーザー入力インターフェースを表示する場合は`true`、表示しない場合は`false`。

```jsx
uneeqInstance.setShowUserInputInterface(true);
```

### startSession()

デジタルヒューマンとのセッションを開始します。

```jsx
uneeqInstance.startSession();
```

### triggerAction(`actionName`)

デジタルヒューマンに実行させるアクションをトリガーします（例：手を振って挨拶する）。

**パラメータ**

`actionName` (string)：トリガーするアクションの名前。各デジタルヒューマンのキャラクターごとに使用可能なアクションのリストは異なる場合があります。また、使用できるアクション名はインラインタグで使用されるものと同じです。

```jsx
uneeqInstance.triggerAction('wavehello');
```

### userStartSpeaking()

ユーザーが発話を開始したことをデジタルヒューマンに通知します。外部の音声入力システムを使用している場合に、ユーザーの発話開始をシステムに伝えるために使用します。

```jsx
uneeqInstance.userStartSpeaking();
```

### userStopSpeaking()

ユーザーが発話を停止したことをデジタルヒューマンに通知します。外部の音声入力システムを使用している場合に、ユーザーの発話停止をシステムに伝えるために使用します。

```jsx
uneeqInstance.userStopSpeaking();
```

### showSnackbar(`message`, `timeout`)

画面下部にスナックバー（トースト通知）を表示します。エラーメッセージや通知の表示に使用されます。

**パラメータ**

* `message` (string): 表示するメッセージ（HTMLを含めることが可能）。
* `timeout` (number): 自動的に非表示になるまでの時間をミリ秒で指定します。`0` を指定するとユーザーがクリックするまで表示し続けます。デフォルト: `3000`。

```jsx
uneeqInstance.showSnackbar('接続に問題が発生しました', 5000);
```

## 機能拡張 DHX Methods

### dhxInit(options)

デジタルヒューマンエクスペリエンス（DHX）の初期化を行います。UneeQインスタンスと各種設定を統合し、DHXの機能を使用可能にします。

> 通常、DHXは`DOMContentLoaded`イベントで自動的に初期化されます。このメソッドは、そのタイミングで`window.dhxOptions`が設定されていなかった場合や、動的に設定を変更したい場合にのみ使用してください。

**パラメータ**

* `options` (object): DHXの設定オプション。UneeQインスタンスや各種フィーチャーの有効/無効設定を含む。

```jsx
const dhxOptions = {
    "uneeq": uneeqInstance,
    "customStt": true,
    "stillcam": true,
    "showStillcamWipe": false
}
window.dhxInit(dhxOptions);
```

### checkDhxOptions()

現在のDHX設定オプションをコンソールに表示し、設定オブジェクトを返します。デバッグや設定確認に使用されます。

```jsx
window.checkDhxOptions();
```

### checkSocketStatus()

ai-orchとのWebsocketの接続状態を確認できます。

```jsx
window.checkSocketStatus();
```

### speakQueue.enqueue(text, addCaption)

デジタルヒューマンの発話をキューに追加し、順次実行します。複数の発話を連続して実行する場合に使用されます。

> 通常提供されている`uneeqInstance.speak`メソッドは、1回目の発話が終了する前に2回目のリクエストを行うと、2回目のリクエスト時点で1回目の発話を停止して次の発話処理を開始します。
>
> この動作により発話が途中で中断される問題を解決するため、キューシステムによる順次実行機能を提供しています。

パラメータ

* `text` (string): デジタルヒューマンに発話させるテキスト。
* `addCaption` (boolean, optional): キャプション表示の有無。デフォルト値はtrue。

```jsx
// 基本的な使用方法
window.speakQueue.enqueue("こんにちは");

// キャプションを表示しない場合
window.speakQueue.enqueue("こんにちは", false);

// 複数の発話を順次実行
window.speakQueue.enqueue("最初の発話です");
window.speakQueue.enqueue("次の発話です");
window.speakQueue.enqueue("最後の発話です");
```

### speakQueue.stopAllSpeaking()

現在の発話を即座に停止し、キューに入っているすべての発話をクリアします。`uneeqInstance.stopSpeaking()` の呼び出しに加えて、キュー内の待機中の発話もすべて削除します。

```jsx
window.speakQueue.stopAllSpeaking();
```

### dhxShowStillcamWipe(show)

静止画キャプチャ機能のワイプエフェクト表示を動的に切り替えます。`dhxOptions.stillcam`機能が有効な場合にのみ使用可能です。

**パラメータ**

* show (boolean): ワイプエフェクトを表示する場合はtrue、非表示にする場合はfalse。

```jsx
// ワイプエフェクトを表示
window.dhxShowStillcamWipe(true);

// ワイプエフェクトを非表示
window.dhxShowStillcamWipe(false);
```

### getSessionDuration()

現在のセッションの経過時間を取得します。`dhxOptions.timeDetail`オプションが有効な場合にのみ使用可能です。セッションがアクティブでない場合は値は返却されません。

```jsx
const duration = window.getSessionDuration();
console.log(duration); // セッション経過時間（秒）
```

### dhxShowSuggestedResponses(suggestedResponses)

画面にサジェストボタンを表示または非表示にします。 表示されたボタンをクリックすると、自動的にチャットプロンプトとして送信されます。

パラメータ:

* suggestedResponses (`Array`|`boolean`|`null`): サジェストレスポンスの配列、または非表示用の値

サジェストレスポンスオブジェクト:

* label (string): ボタンに表示されるテキスト
* utterance (string): クリック時に送信されるメッセージ

表示例:

```jsx
window.dhxShowSuggestedResponses([
    { label: "はい", utterance: "はい" },
    { label: "いいえ", utterance: "いいえ" },
    { label: "詳しく教えて", utterance: "詳しく教えてください" }
]);
```

非表示例:

```jsx
window.dhxShowSuggestedResponses(false);
// または
window.dhxShowSuggestedResponses(null);
// または
window.dhxShowSuggestedResponses([]);
```