## JavaScript API 関数仕様

### 基本・ページ遷移

#### void log(string mes)

暗号化ログへ出力（改行は自動付与）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `mes` | `string` | 必須 | 文字列。 |

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.log('');
```

#### void showMessage(string msg)

Windows はメッセージボックス、Android はトースト表示。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `msg` | `string` | 必須 | 文字列。 |

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.showMessage('');
```

#### void exit()

アプリ終了。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.exit();
```

#### void finish()

ホストの終了処理を呼ぶ。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.finish();
```

#### void loadUrl(string url)

`%APP%` / `%HOME%` プレースホルダ可。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 備考

`file://` URI も許容。他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.loadUrl('https://example.com/');
```

#### void openUrl(string url)

`loadUrl` の別名。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.openUrl('https://example.com/');
```

#### void settings()

Windows は設定ページを読み込み、Android は OS の設定アプリを起動。

- **対応プラットフォーム**: Windows △ / Android △
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.settings();
```

#### void loadMyHome()

トップページを読み込む。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.loadMyHome();
```

#### void goHome()

トップページに戻る。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.goHome();
```

#### void historyBack()

履歴を 1 つ戻る。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.historyBack();
```

#### void clearHistory()

閲覧履歴をクリア。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.clearHistory();
```

#### void nativeToJavascript(string func)

メイン WebView で JavaScript を実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `func` | `string` | 必須 | 文字列。 |

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.nativeToJavascript('');
```

#### void eval(string cmd)

メイン WebView で JavaScript を実行（nativeToJavascript と同等）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `cmd` | `string` | 必須 | 文字列。 |

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.eval('');
```

#### void splashFinished()

Android のみ。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 前提・後続 API

**Android のみ**。スプラッシュ画面からホーム遷移を完了させる。ドメインチェックを行わない。Android スプラッシュ画面から呼び出すことを想定

##### サンプル

```javascript
window.sticktv.splashFinished();
```


---

### 設定保存（Preference）

`setPreferenceString` / `getPreferenceString` は文字列値を AES で暗号化して保存・取得します（固定キー）。
`setPreferenceInt` / `getPreferenceInt` / `setPreferenceBoolean` / `getPreferenceBoolean` は平文で保存します。

Windows の保存キーは `type + "_" + key`（`type` が空の場合は `key` のみ）。
Android では `type` が空の場合はデフォルトプリファレンス、それ以外の場合は `type` 名のプリファレンスファイルに `key` で保存します。

#### void setPreferenceString(string type, string key, string value)

文字列として AES 暗号化保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | 文字列。 |
| `key` | `string` | 必須 | 文字列。 |
| `value` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

文字列として AES 暗号化保存。Windows 第 3 引数は実装上 `object` 型（JS からは文字列を渡す）。対応する `getPreferenceString` は設定後に呼び出す

##### サンプル

```javascript
window.sticktv.setPreferenceString('', '', '');
```

#### string getPreferenceString(string type, string key)

復号して取得。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | 文字列。 |
| `key` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

復号して取得。失敗時は生の値。未設定時は空文字。対応する `setPreferenceString` の後に呼び出す

##### サンプル

```javascript
const result = await window.sticktv.getPreferenceString('', '');
console.log(result);
```

#### void setPreferenceInt(string type, string key, int value)

整数値を平文で保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | 文字列。 |
| `key` | `string` | 必須 | 文字列。 |
| `value` | `int` | 必須 | 数値。 |

##### 前提・後続 API

整数値を平文で保存。Windows 第 3 引数は実装上 `object` 型（JS からは数値を渡す）。対応する `getPreferenceInt` は設定後に呼び出す

##### サンプル

```javascript
window.sticktv.setPreferenceInt('', '', 0);
```

#### string getPreferenceInt(string type, string key)

整数値の文字列表現を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | 文字列。 |
| `key` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

整数値の文字列表現を返す。対応する `setPreferenceInt` の後に呼び出す

##### サンプル

```javascript
const result = await window.sticktv.getPreferenceInt('', '');
console.log(result);
```

#### void setPreferenceBoolean(string type, string key, bool value)

真偽値を平文で保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | 文字列。 |
| `key` | `string` | 必須 | 文字列。 |
| `value` | `bool` | 必須 | 真偽値。 |

##### 前提・後続 API

真偽値を平文で保存。Windows 第 3 引数は実装上 `object` 型（JS からは真偽値を渡す）。対応する `getPreferenceBoolean` は設定後に呼び出す

##### サンプル

```javascript
window.sticktv.setPreferenceBoolean('', '', true);
```

#### string getPreferenceBoolean(string type, string key)

`"true"` / `"false"` を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | 文字列。 |
| `key` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

`"true"` / `"false"` を返す。対応する `setPreferenceBoolean` の後に呼び出す

##### サンプル

```javascript
const result = await window.sticktv.getPreferenceBoolean('', '');
console.log(result);
```

#### void initPreference()

設定を全てリセット。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

設定を全てリセット。`getPreference*` の前に呼び出すと保存済み値が失われるため注意

##### サンプル

```javascript
window.sticktv.initPreference();
```


### JavaScript 変数（キー値ストア）

内部的なキー値ストアを保持し、値を JSON にシリアライズして Preference 領域に永続化します。

#### void setVar(string key, string value)

Windows は `value` に `bool` / `int` を渡すと文字列化して保存（それ以外の型は警告）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `key` | `string` | 必須 | 文字列。 |
| `value` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

Windows は `value` に `bool` / `int` を渡すと文字列化して保存（それ以外の型は警告）。対応する `getVar` は設定後に呼び出す

##### サンプル

```javascript
window.sticktv.setVar('', '');
```

#### string getVar(string key)

未登録キーは永続化領域から読み込み、通常は空文字。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `key` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

未登録キーは永続化領域から読み込み、通常は空文字。Windows 版では Preference 復号に失敗すると例外が発生する可能性がある。対応する `setVar` の後に呼び出す

##### サンプル

```javascript
const result = await window.sticktv.getVar('');
console.log(result);
```

#### void removeVar(string key)

一時領域と永続化領域の両方から削除。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `key` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

一時領域と永続化領域の両方から削除。対応する `setVar` 実行後に呼び出す

##### サンプル

```javascript
window.sticktv.removeVar('');
```


---

### ファイル・フォルダ操作

#### bool fileExists(string path)

`path` には `file://` URI も許容。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 備考

他 API との呼び出し順序の前提はない

##### サンプル

```javascript
const ok = await window.sticktv.fileExists('%APP%/data/file.txt');
if (!ok) console.error('fileExists 失敗');
```

#### void removeFile(string path)

`path` には `file://` URI も許容。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 前提・後続 API

`path` には `file://` URI も許容。`fileExists` で存在確認後に呼び出すことを推奨

##### サンプル

```javascript
window.sticktv.removeFile('%APP%/data/file.txt');
```

#### void removeFolder(string path)

フォルダを再帰削除。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 前提・後続 API

フォルダを再帰削除。`path` には `file://` URI も許容。`getFolderTree` 等で対象を確認後に呼び出すことを推奨

##### サンプル

```javascript
window.sticktv.removeFolder('%APP%/data/file.txt');
```

#### void removeFolder2Day(string path)

作成から 2 日以上経過したファイルを削除。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 備考

`path` には `file://` URI も許容。**Android はバックグラウンドスレッドで実行し、呼び出しは即座に返る**。他 API との呼び出し順序の前提はない

##### サンプル

```javascript
window.sticktv.removeFolder2Day('%APP%/data/file.txt');
```

#### bool writeFile(string path, string text)

UTF-8 で上書き保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `text` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 備考

`path` には `file://` URI も許容。親フォルダは自動作成。対象パスは `getFilesDir` 等で取得することが多い

##### サンプル

```javascript
const ok = await window.sticktv.writeFile('%APP%/data/file.txt', '');
if (!ok) console.error('writeFile 失敗');
```

#### bool writeFileCSV(string path, string text)

BOM 付き UTF-8 で上書き保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `text` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 備考

`path` には `file://` URI も許容。対象パスは `getFilesDir` 等で取得することが多い

##### サンプル

```javascript
const ok = await window.sticktv.writeFileCSV('%APP%/data/file.txt', '');
if (!ok) console.error('writeFileCSV 失敗');
```

#### string getFolderList(string path)

Windows: サブフォルダも含む相対パスを改行区切りで返す。

- **対応プラットフォーム**: Windows △ / Android △
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

**Windows**: サブフォルダも含む相対パスを改行区切りで返す。**Android**: 直下ファイル名のみを改行区切りで返す。`path` には `file://` URI も許容。`removeFolder` / `writeFile` の前に呼び出すことを推奨

##### サンプル

```javascript
const result = await window.sticktv.getFolderList('%APP%/data/file.txt');
console.log(result);
```

#### string getFolderTree(string path)

サブフォルダを含む相対パス一覧（`/` 区切り、改行区切り）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

サブフォルダを含む相対パス一覧（`/` 区切り、改行区切り）。`path` には `file://` URI も許容。`removeFolder` / `writeFile` の前に呼び出すことを推奨

##### サンプル

```javascript
const result = await window.sticktv.getFolderTree('%APP%/data/file.txt');
console.log(result);
```

#### string getDirList(string path)

ファイル・フォルダ名を改行区切りで返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

ファイル・フォルダ名を改行区切りで返す。`path` には `file://` URI も許容。`removeFolder` / `writeFile` の前に呼び出すことを推奨

##### サンプル

```javascript
const result = await window.sticktv.getDirList('%APP%/data/file.txt');
console.log(result);
```

#### string getFilesDir()

Windows はアプリ作業ディレクトリの絶対パス。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

Android はキャッシュディレクトリの絶対パス。`writeFile` / `getUrl` 等のパス取得に使うことが多い

##### サンプル

```javascript
const result = await window.sticktv.getFilesDir();
console.log(result);
```

#### void unzipfile(string zipFilePath, string destinationPath, string password)

ZIP 解凍。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `zipFilePath` | `string` | 必須 | 文字列。 |
| `destinationPath` | `string` | 必須 | 文字列。 |
| `password` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

ZIP 解凍。`zipFilePath` / `destinationPath` には `file://` URI も許容。パスワード付き ZIP も両プラットフォームで対応。`fileExists` で対象 ZIP の存在を確認後に呼び出すことを推奨

##### サンプル

```javascript
window.sticktv.unzipfile('', '', '');
```

#### string convAppUrl(string url)

`%APP%` / `%HOME%` を展開した URL を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

`%APP%` / `%HOME%` を展開した URL を返す。`getUrl` / `loadUrl` 等の前に呼び出すことがある

##### サンプル

```javascript
const result = await window.sticktv.convAppUrl('https://example.com/');
console.log(result);
```

#### string convAppPath(string path)

`%APP%` / `%HOME%` を展開したローカルパスを返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

`%APP%` / `%HOME%` を展開したローカルパスを返す。`writeFile` / `getUrl` 等の前に呼び出すことがある

##### サンプル

```javascript
const result = await window.sticktv.convAppPath('%APP%/data/file.txt');
console.log(result);
```

#### void decodeLogs()

暗号化ログを復号してテキストファイルに保存（詳細は 2.25）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

暗号化ログを復号してテキストファイルに保存（詳細は 2.25）。`log` 出力後に呼び出す

##### サンプル

```javascript
window.sticktv.decodeLogs();
```

#### string pickFile(string optionsJson)

ファイル選択ダイアログを開く。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### 戻り値 JSON スキーマ

成功時:

```json
{"uri":"file:///C:/path/to/file.jpg","name":"file.jpg"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `uri` | `string` | 選択/保存されたファイルの URI。Windows は `file:///...`、Android は `content://...` |
| `name` | `string` | ファイル名 |

キャンセル時:

```json
{"cancelled":true}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `cancelled` | `boolean` | ユーザーがキャンセルした場合 `true` |
##### 前提・後続 API

ファイル選択ダイアログを開く。戻り値は `{"uri":"...", "name":"..."}`。キャンセル時は `{"cancelled":true}`。Windows では `file:///...` URI、Android では `content://...` URI。取得した `uri` は `getUrl` 等の前に使う

##### サンプル

```javascript
const result = await window.sticktv.pickFile(JSON.stringify({}));
console.log(result);
```

#### void asyncPickFile(string optionsJson, string callback)

`pickFile` の非同期版。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### コールバック JSON スキーマ

成功時:

```json
{"uri":"file:///C:/path/to/file.jpg","name":"file.jpg"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `uri` | `string` | 選択/保存されたファイルの URI。Windows は `file:///...`、Android は `content://...` |
| `name` | `string` | ファイル名 |

キャンセル時:

```json
{"cancelled":true}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `cancelled` | `boolean` | ユーザーがキャンセルした場合 `true` |
##### 前提・後続 API

`pickFile` の非同期版。完了時 `callback(resultJson)` を実行。コールバック関数名は事前に定義しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncPickFile(JSON.stringify({}), 'onResult');
```

#### string pickFiles(string optionsJson)

複数ファイル選択。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### 戻り値 JSON スキーマ

成功時:

```json
{"items":[{"uri":"...","name":"..."}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `items` | `object[]` | 選択されたファイルオブジェクトの配列 |
| `items[].uri` | `string` | ファイル URI |
| `items[].name` | `string` | ファイル名 |
##### 前提・後続 API

複数ファイル選択。戻り値は `{"items":[{"uri":"...", "name":"..."}, ...]}`. 取得した各 `uri` は `getUrl` 等の前に使う

##### サンプル

```javascript
const result = await window.sticktv.pickFiles(JSON.stringify({}));
console.log(result);
```

#### void asyncPickFiles(string optionsJson, string callback)

`pickFiles` の非同期版。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### コールバック JSON スキーマ

成功時:

```json
{"items":[{"uri":"...","name":"..."}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `items` | `object[]` | 選択されたファイルオブジェクトの配列 |
| `items[].uri` | `string` | ファイル URI |
| `items[].name` | `string` | ファイル名 |
##### 前提・後続 API

`pickFiles` の非同期版。コールバック関数名は事前に定義しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncPickFiles(JSON.stringify({}), 'onResult');
```

#### string pickFolder(string optionsJson)

フォルダ選択ダイアログを開く。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### 戻り値 JSON スキーマ

成功時:

```json
{"uri":"file:///C:/path/to/file.jpg","name":"file.jpg"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `uri` | `string` | 選択/保存されたファイルの URI。Windows は `file:///...`、Android は `content://...` |
| `name` | `string` | ファイル名 |

キャンセル時:

```json
{"cancelled":true}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `cancelled` | `boolean` | ユーザーがキャンセルした場合 `true` |
##### 前提・後続 API

フォルダ選択ダイアログを開く。戻り値形式は `pickFile` と同じ。取得した `uri` は `getFolderTree` / `writeFile` 等の前に使う

##### サンプル

```javascript
const result = await window.sticktv.pickFolder(JSON.stringify({}));
console.log(result);
```

#### void asyncPickFolder(string optionsJson, string callback)

`pickFolder` の非同期版。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### コールバック JSON スキーマ

成功時:

```json
{"uri":"file:///C:/path/to/file.jpg","name":"file.jpg"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `uri` | `string` | 選択/保存されたファイルの URI。Windows は `file:///...`、Android は `content://...` |
| `name` | `string` | ファイル名 |

キャンセル時:

```json
{"cancelled":true}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `cancelled` | `boolean` | ユーザーがキャンセルした場合 `true` |
##### 前提・後続 API

`pickFolder` の非同期版。コールバック関数名は事前に定義しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncPickFolder(JSON.stringify({}), 'onResult');
```

#### string saveFile(string optionsJson)

保存先ファイル選択ダイアログを開く。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### 戻り値 JSON スキーマ

成功時:

```json
{"uri":"file:///C:/path/to/file.jpg","name":"file.jpg"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `uri` | `string` | 選択/保存されたファイルの URI。Windows は `file:///...`、Android は `content://...` |
| `name` | `string` | ファイル名 |

キャンセル時:

```json
{"cancelled":true}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `cancelled` | `boolean` | ユーザーがキャンセルした場合 `true` |
##### 前提・後続 API

保存先ファイル選択ダイアログを開く。`defaultFileName` で初期ファイル名を指定可。戻り値の `uri` は `writeFile` の前に使う

##### サンプル

```javascript
const result = await window.sticktv.saveFile(JSON.stringify({}));
console.log(result);
```

#### void asyncSaveFile(string optionsJson, string callback)

`saveFile` の非同期版。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `title` | `string` | 任意 | ダイアログのタイトル |
| `filters` | `object[]` | 任意 | 選択可能なファイル種別の配列 |
| `filters[].name` | `string` | 必須 | フィルターの表示名 |
| `filters[].extensions` | `string[]` | 必須 | 拡張子の配列。`["*"]` ですべてのファイルを対象にする |
| `initialDirectory` | `string` | 任意 | 初期表示フォルダ。`%APP%` / `%HOME%` プレースホルダ可 |
| `defaultFileName` | `string` | 任意 | 保存ダイアログ（`saveFile` / `asyncSaveFile`）の初期ファイル名 |

##### コールバック JSON スキーマ

成功時:

```json
{"uri":"file:///C:/path/to/file.jpg","name":"file.jpg"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `uri` | `string` | 選択/保存されたファイルの URI。Windows は `file:///...`、Android は `content://...` |
| `name` | `string` | ファイル名 |

キャンセル時:

```json
{"cancelled":true}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `cancelled` | `boolean` | ユーザーがキャンセルした場合 `true` |
##### 前提・後続 API

`saveFile` の非同期版。コールバック関数名は事前に定義しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncSaveFile(JSON.stringify({}), 'onResult');
```


### ダウンロード・HTTP

#### bool downloadPath(string path, string url)

同期的にダウンロードして待つ。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

同期的にダウンロードして待つ。`path` には `file://` URI も許容。UI がブロックされることがある。ダウンロード後に `getUrl` / `getDataBase64` 等で内容を読むことが多い

##### サンプル

```javascript
const ok = await window.sticktv.downloadPath('%APP%/data/file.txt', 'https://example.com/');
if (!ok) console.error('downloadPath 失敗');
```

#### void asyncDownloadPath(string path, string url)

Windows も真に非同期（`Task.Run`）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 備考

`path` には `file://` URI も許容。完了を待たない。完了検知は個別に実装する必要がある

##### サンプル

```javascript
window.sticktv.asyncDownloadPath('%APP%/data/file.txt', 'https://example.com/');
```

#### bool asyncDownloadPath(string path, string url, bool overwrite)

開始可否を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |
| `overwrite` | `bool` | 必須 | 真偽値。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 備考

`path` には `file://` URI も許容。ダウンロード完了は待たない。`overwrite=false` で既存ファイル時はスキップ

##### サンプル

```javascript
const ok = await window.sticktv.asyncDownloadPath('%APP%/data/file.txt', 'https://example.com/', true);
if (!ok) console.error('asyncDownloadPath 失敗');
```

#### string getUrl(string url)

指定 URL / file パスの内容を文字列で取得。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

指定 URL / file パスの内容を文字列で取得。`file://` URI も許容。`pickFile` / `downloadPath` / `convAppUrl` の後に呼び出すことが多い

##### サンプル

```javascript
const result = await window.sticktv.getUrl('https://example.com/');
console.log(result);
```

#### void asyncGetUrl(string url, string callback)

非同期取得。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 前提・後続 API

非同期取得。`url` には `file://` URI も許容。`callback('エスケープ済み文字列')` で通知。コールバック関数名は事前に定義しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncGetUrl('https://example.com/', 'onResult');
```


### 画像

#### void shrinkPhoto(string path, int width, int height, bool reverseUpDown, bool reverseLeftRight)

リサイズして JPEG 上書き保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `width` | `int` | 必須 | 数値。 |
| `height` | `int` | 必須 | 数値。 |
| `reverseUpDown` | `bool` | 必須 | 真偽値。 |
| `reverseLeftRight` | `bool` | 必須 | 真偽値。 |

##### 前提・後続 API

リサイズして JPEG 上書き保存。`path` には `file://` URI も許容。**Windows 版は `reverseUpDown` / `reverseLeftRight` を無視**（Android のみ反転が有効）。`getDataBase64` / `openaiChatImage` の前に呼び出すことを推奨

##### サンプル

```javascript
window.sticktv.shrinkPhoto('%APP%/data/file.txt', 0, 0, true, true);
```

#### string getPhotoSize(string path)

画像の実サイズを `"幅x高さ"` で返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

画像の実サイズを `"幅x高さ"` で返す。`path` には `file://` URI も許容。`shrinkPhoto` / `getDataBase64` の前に呼び出すことがある

##### サンプル

```javascript
const result = await window.sticktv.getPhotoSize('%APP%/data/file.txt');
console.log(result);
```

#### void saveJpeg(string filePath, string data)

Base64 画像を JPEG として保存。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `filePath` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |
| `data` | `string` | 必須 | Base64 エンコード済みデータ。 |

##### 前提・後続 API

Base64 画像を JPEG として保存。`filePath` には `file://` URI も許容。保存後に `getDataBase64` / `getUrl` 等で読み出す

##### サンプル

```javascript
window.sticktv.saveJpeg('%APP%/data/file.txt', 'data:image/png;base64,...');
```

#### string getDataBase64(string path)

PNG に変換した `data:image/png;base64,...` を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `path` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

PNG に変換した `data:image/png;base64,...` を返す。`path` には `file://` URI も許容。失敗時は空文字。`openaiChatImage` / `asyncOpenaiChatImage` / `getUrlBase64` の前に呼び出すことが多い

##### サンプル

```javascript
const result = await window.sticktv.getDataBase64('%APP%/data/file.txt');
console.log(result);
```

#### string getUrlBase64(string url)

`data:<mime>;base64,...` または `file://` URI から取得。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

`data:<mime>;base64,...` または `file://` URI から取得。失敗時は空文字。`openaiChatImage` の前に呼び出すことがある

##### サンプル

```javascript
const result = await window.sticktv.getUrlBase64('https://example.com/');
console.log(result);
```

#### string getFileBytes(string filename)

ファイル内容を Base64 文字列で返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `filename` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、またはローカルパス。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

`filename` には `file://` URI も許容。他 API との呼び出し順序の前提はない

##### サンプル

```javascript
const result = await window.sticktv.getFileBytes('%APP%/data/file.txt');
console.log(result);
```

#### int printPngUrl(string url)

Windows は PNG を既定プリンタへ印刷。

- **対応プラットフォーム**: Windows △ / Android △
- **戻り値**: `int`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `int` | 整数値。失敗時 `-1`（但し `printPngUrl` 等の例外あり）。 |

##### 備考

`url` には `file://` URI も許容。戻り値は **原則 `0`**（内部の印刷失敗は握りつぶされ、JsObject レベルで外部例外が発生した場合のみ `-1`）。Android は未実装で通常 **固定値 `-999999`** を返す。許可ドメイン外では `-1`。他 API との呼び出し順序の前提はない

##### サンプル

```javascript
const result = await window.sticktv.printPngUrl('https://example.com/');
console.log(result);
```


---

### TWAIN スキャナー（Windows のみ）

TWAIN 対応スキャナーから画像を取得し、base64 data URL として返します。取得した画像はメモリ上で PNG に変換され、一時ファイルを作成しません。

#### string scanTwainListDevices()

`[{"id":"...","name":"..."}]` 形式。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
[{"id":"...","name":"..."}]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `id` | `string` | デバイス識別子 |
| `name` | `string` | デバイス表示名 |
##### 前提・後続 API

`[{"id":"...","name":"..."}]` 形式。失敗時は `"[]"`。取得後、得た `id` を使って `scanTwainImage()` / `asyncScanTwainImage()` を呼び出す

##### サンプル

```javascript
const result = await window.sticktv.scanTwainListDevices();
console.log(result);
```

#### string scanTwainImage(string optionsJson)

成功時は `{"success":true,"base64":"data:image/png;base64,...","width":...,"height":...,"dpi":...,"colorMode":"..."}`。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `deviceId` | `string` | 任意 | `scanTwainListDevices()` で取得した `id`。未指定または無効な場合は TWAIN ソース選択ダイアログを表示 |
| `dpi` | `number` | 任意 | 解像度。省略時は `200` |
| `colorMode` | `string` | 任意 | `"color"` / `"gray"` / `"bw"`。省略時は `"color"`。内部は PNG として base64 化 |
| `showUI` | `boolean` | 任意 | `true` の場合、スキャナー提供の UI を表示。省略時は `true` |

##### 戻り値 JSON スキーマ

成功時:

```json
{"success":true,"base64":"data:image/png;base64,...","width":...,"height":...,"dpi":...,"colorMode":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `success` | `boolean` | 成功時 `true` |
| `base64` | `string` | PNG 化された画像の data URL |
| `width` | `number` | 画像幅（ピクセル） |
| `height` | `number` | 画像高さ（ピクセル） |
| `dpi` | `number` | 解像度 |
| `colorMode` | `string` | `"color"` / `"gray"` / `"bw"` |

失敗時:

```json
{"success":false,"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `success` | `boolean` | 失敗時 `false` |
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

成功時は `{"success":true,"base64":"data:image/png;base64,...","width":...,"height":...,"dpi":...,"colorMode":"..."}`。失敗時は `{"success":false,"error":"..."}`。実際にスキャンする前に `scanTwainListDevices()` で対象 `id` を取得しておくこと

##### サンプル

```javascript
const result = await window.sticktv.scanTwainImage(JSON.stringify({}));
console.log(result);
```

#### void asyncScanTwainImage(string optionsJson, string callback)

非同期版。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `deviceId` | `string` | 任意 | `scanTwainListDevices()` で取得した `id`。未指定または無効な場合は TWAIN ソース選択ダイアログを表示 |
| `dpi` | `number` | 任意 | 解像度。省略時は `200` |
| `colorMode` | `string` | 任意 | `"color"` / `"gray"` / `"bw"`。省略時は `"color"`。内部は PNG として base64 化 |
| `showUI` | `boolean` | 任意 | `true` の場合、スキャナー提供の UI を表示。省略時は `true` |

##### コールバック JSON スキーマ

成功時:

```json
{"success":true,"base64":"data:image/png;base64,...","width":...,"height":...,"dpi":...,"colorMode":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `success` | `boolean` | 成功時 `true` |
| `base64` | `string` | PNG 化された画像の data URL |
| `width` | `number` | 画像幅（ピクセル） |
| `height` | `number` | 画像高さ（ピクセル） |
| `dpi` | `number` | 解像度 |
| `colorMode` | `string` | `"color"` / `"gray"` / `"bw"` |

失敗時:

```json
{"success":false,"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `success` | `boolean` | 失敗時 `false` |
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

非同期版。完了時に `callback(resultJson)` を実行。呼び出し前に `scanTwainListDevices()` で対象 `id` を取得しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncScanTwainImage(JSON.stringify({}), 'onResult');
```


### 印刷（ESC/POS サーマルプリンタ）

ネイティブ側は生バイト列の送受信（`printWrite`）とデバイス列挙（`printListDevices`）のみを担当します。
レシートマークアップから ESC/POS コマンドへの変換は、`sticktv_stub.js` が読み込む ReceiptLine ライブラリで行います。ネイティブ `JsObject` には `printReceipt` は存在しません。

#### bool printWrite(string base64Bytes, string optionsJson)

Base64 エンコードされた ESC/POS バイト列を印刷。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `base64Bytes` | `string` | 必須 | 文字列。 |
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### optionsJson の JSON スキーマ

接続タイプ共通:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | `usb-serial` / `usb-print` / `tcp` / `usb` / `bluetooth-spp` |

`usb-serial`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `port` | `string` | 必須 | COM ポート名（例: `"COM3"`） |
| `baudRate` | `number` | 任意 | ボーレート。省略時はプリンタ依存（通常 `115200` 等） |
| `dataBits` | `number` | 任意 | データビット数 |
| `parity` | `string` | 任意 | パリティ（`"none"` 等） |
| `stopBits` | `number` | 任意 | ストップビット数 |

`usb-print`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `devicePath` | `string` | 必須 | `printListDevices()` で取得した Windows デバイスパス |

`tcp`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `host` | `string` | 必須 | プリンタの IP またはホスト名 |
| `port` | `number` | 必須 | ポート番号 |

`usb`（Android USB ホスト）:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `vendorId` | `number` | 必須 | USB Vendor ID |
| `productId` | `number` | 必須 | USB Product ID |

`bluetooth-spp`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | ペアリング済み Bluetooth デバイスの MAC アドレス |
##### 前提・後続 API

Base64 エンコードされた ESC/POS バイト列を印刷。接続は毎回オープン・書き込み・クローズ。呼び出し前に `printListDevices()` で対象 `port` / `devicePath` / `address` などを確認し、`optionsJson` に含めることを推奨

##### サンプル

```javascript
const ok = await window.sticktv.printWrite('', JSON.stringify({}));
if (!ok) console.error('printWrite 失敗');
```

#### string printListDevices()

利用可能な印刷デバイスの JSON 配列。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
[
  {"type":"usb-serial","name":"COM3","port":"COM3"},
  {"type":"usb-print","name":"USB 印刷","devicePath":"\\?\usb#..."},
  {"type":"tcp","name":"192.168.1.10:9100","host":"192.168.1.10","port":9100},
  {"type":"usb","name":"USB Device","vendorId":1305,"productId":1},
  {"type":"bluetooth-spp","name":"Printer","address":"AA:BB:CC:DD:EE:FF"}
]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `type` | `string` | 接続タイプ。`usb-serial` / `usb-print` / `tcp` / `usb` / `bluetooth-spp` |
| `name` | `string` | デバイス表示名 |
| `port` | `string` | `usb-serial` 時の COM ポート名 |
| `devicePath` | `string` | `usb-print` 時の Windows デバイスパス |
| `host` | `string` | `tcp` 時のホスト名/IP |
| `port` | `number` | `tcp` 時のポート番号 |
| `vendorId` | `number` | `usb` 時の USB Vendor ID |
| `productId` | `number` | `usb` 時の USB Product ID |
| `address` | `string` | `bluetooth-spp` 時の MAC アドレス |
##### 前提・後続 API

利用可能な印刷デバイスの JSON 配列。Windows は COM ポート、USB-Print デバイス、ペアリング済み Bluetooth SPP デバイスを列挙。Android は USB ホストデバイスとペアリング済み Bluetooth SPP デバイスを列挙。取得結果をもとに `printWrite()` / `printReceipt()` を呼び出す

##### サンプル

```javascript
const result = await window.sticktv.printListDevices();
console.log(result);
```

#### bool printReceipt(string receiptLineMarkup, string optionsJson)

`sticktv_stub.js` 提供のヘルパー。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `receiptLineMarkup` | `string` | 必須 | 文字列。 |
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### optionsJson の JSON スキーマ

接続タイプ共通:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | `string` | 必須 | `usb-serial` / `usb-print` / `tcp` / `usb` / `bluetooth-spp` |

`usb-serial`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `port` | `string` | 必須 | COM ポート名（例: `"COM3"`） |
| `baudRate` | `number` | 任意 | ボーレート。省略時はプリンタ依存（通常 `115200` 等） |
| `dataBits` | `number` | 任意 | データビット数 |
| `parity` | `string` | 任意 | パリティ（`"none"` 等） |
| `stopBits` | `number` | 任意 | ストップビット数 |

`usb-print`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `devicePath` | `string` | 必須 | `printListDevices()` で取得した Windows デバイスパス |

`tcp`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `host` | `string` | 必須 | プリンタの IP またはホスト名 |
| `port` | `number` | 必須 | ポート番号 |

`usb`（Android USB ホスト）:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `vendorId` | `number` | 必須 | USB Vendor ID |
| `productId` | `number` | 必須 | USB Product ID |

`bluetooth-spp`:

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | ペアリング済み Bluetooth デバイスの MAC アドレス |

##### `receiptline` フィールドの JSON スキーマ

```json
{ "command": "escpos", "encoding": "shiftjis", "cpl": 32 }
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `command` | `string` | 任意 | プリンタコマンド体系。省略時 `escpos` |
| `encoding` | `string` | 任意 | 文字エンコーディング。省略時 `shiftjis` |
| `cpl` | `number` | 任意 | 1 行の文字数。省略時 `32` |
##### 前提・後続 API

**`sticktv_stub.js` 提供のヘルパー**。ReceiptLine マークアップを変換して `printWrite` を実行。ネイティブ `JsObject` には存在しない。`printListDevices()` で対象を確認してから呼び出すことを推奨

##### サンプル

```javascript
const ok = await window.sticktv.printReceipt('', JSON.stringify({}));
if (!ok) console.error('printReceipt 失敗');
```


### 動画サブフレーム

メイン画面の上に動画専用サブフレームを重ねて表示します。

#### void openSubFrameVideo(int x, int y, int w, int h, float scale, string url)

動画サブフレームを開く。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `x` | `int` | 必須 | 数値。 |
| `y` | `int` | 必須 | 数値。 |
| `w` | `int` | 必須 | 数値。 |
| `h` | `int` | 必須 | 数値。 |
| `scale` | `float` | 必須 | 数値。 |
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 前提・後続 API

動画サブフレームを開く。`url` には `file://` URI も許容。開いた後に `setSubFrameVideo()` / `setSubFrameVideoVisibility()` を使う。終了時は `closeSubFrameVideo()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.openSubFrameVideo(0, 0, 0, 0, 1.0, 'https://example.com/');
```

#### void closeSubFrameVideo()

開いた動画サブフレームを閉じる。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

開いた動画サブフレームを閉じる。`openSubFrameVideo()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.closeSubFrameVideo();
```

#### void setSubFrameVideo(string url)

再生中サブフレームの URL を変更。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 前提・後続 API

再生中サブフレームの URL を変更。`url` には `file://` URI も許容。`openSubFrameVideo()` 後に呼び出すこと

##### サンプル

```javascript
window.sticktv.setSubFrameVideo('https://example.com/');
```

#### void setSubFrameVideoVisibility(bool visible)

表示/非表示を切り替える。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `visible` | `bool` | 必須 | 真偽値。 |

##### 前提・後続 API

表示/非表示を切り替える。`openSubFrameVideo()` 後に呼び出すこと

##### サンプル

```javascript
window.sticktv.setSubFrameVideoVisibility(true);
```


備考（Windows 版）: 終了時やエラー時にはリプレイ用オーバーレイ画像が表示され、動画サブフレームはマウス左クリックで先頭から再生し直せます。

### サブフレームウィンドウ

メイン画面の上に子ウィンドウを重ねて表示します（Windows は子 WebView2、Android は HTML サブウィンドウ）。子側にも `window.sticktv` が注入されます。

#### void openSubFrameWindow(int x, int y, int w, int h, float scale, string url)

子ウィンドウを開く。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `x` | `int` | 必須 | 数値。 |
| `y` | `int` | 必須 | 数値。 |
| `w` | `int` | 必須 | 数値。 |
| `h` | `int` | 必須 | 数値。 |
| `scale` | `float` | 必須 | 数値。 |
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 前提・後続 API

子ウィンドウを開く。`url` には `file://` URI も許容。Windows はサイズ・倍率が有効な場合のみ開始。Android は `url` を指定して即座に読み込む。開いた後に `evalSubFrameWindow()` / `setSubFrameWindowVisibility()` を使う。終了時は `closeSubFrameWindow()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.openSubFrameWindow(0, 0, 0, 0, 1.0, 'https://example.com/');
```

#### void closeSubFrameWindow()

子ウィンドウを閉じる（動画サブフレームも同時に閉じる）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

子ウィンドウを閉じる（動画サブフレームも同時に閉じる）。`openSubFrameWindow()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.closeSubFrameWindow();
```

#### void setSubFrameWindowVisibility(bool visible)

表示/非表示を切り替える。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `visible` | `bool` | 必須 | 真偽値。 |

##### 前提・後続 API

表示/非表示を切り替える。`openSubFrameWindow()` 後に呼び出すこと

##### サンプル

```javascript
window.sticktv.setSubFrameWindowVisibility(true);
```

#### void evalSubFrameWindow(string exp)

サブフレーム（本節の子ウィンドウ）内で JavaScript を評価（結果は取得できない）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `exp` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

**サブフレーム**（本節の子ウィンドウ）内で JavaScript を評価（結果は取得できない）。`openSubFrameWindow()` で開いた対象に対して使用する。終了時は `closeSubFrameWindow()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.evalSubFrameWindow('');
```


### 顔検出

カメラ映像から顔を検出し、`callback(json)` 形式で通知します。JSON 形式: `[{"name":"顔検出","value":N}]`（N は検出顔数）。

```javascript
sticktv.startFaceDetect('onFaceDetect', false);
function onFaceDetect(result) {
  const faces = JSON.parse(result); // faces[0].value が検出顔数
}
```

#### void startFaceDetect(string callback, bool isFlipY)

カメラを開始して検出。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |
| `isFlipY` | `bool` | 必須 | 真偽値。 |

##### 前提・後続 API

カメラを開始して検出。`callback` は呼び出し前に定義しておくこと。停止時は対となる `stopFaceDetect()` を呼び出すこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.startFaceDetect('onResult', true);
```

#### void stopFaceDetect()

カメラと顔検出を停止。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

カメラと顔検出を停止。`startFaceDetect()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.stopFaceDetect();
```

#### bool enableFaceDetect()

設定（`useFaceDetect` / FACEDETECT）の値を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 備考

機能が有効になってから `startFaceDetect()` を使うことを推奨

##### サンプル

```javascript
const ok = await window.sticktv.enableFaceDetect();
if (!ok) console.error('enableFaceDetect 失敗');
```


### 物体検出（Object Detection / ONNX）

ONNX モデルをロードし、カメラ映像または静止画像から物体を検出します。モデル種別（YOLO / Faster R-CNN / 独自モデル）は出力メタデータから自動判定します。`labelsJson` が空の場合は既定ラベル（YOLO 系は COCO 80 クラス、Faster R-CNN は torchvision COCO 91 クラス）を使用します。

> **注意:** ローカル ONNX 物体検出はモデルサイズ・画像解像度に応じて処理負荷が高くなります。リアルタイム検出が必須でない場合は、画像を AI 画像解析（`openaiChatImage` / `asyncOpenaiChatImage`）に送る方が軽量かつ柔軟な判定ができます。

#### bool startObjectDetect(string callback, string modelPath, string labelsJson, double confidence)

Windows は起動失敗時に `false`。

- **対応プラットフォーム**: Windows ○ / Android △
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |
| `modelPath` | `string` | 必須 | ONNX モデルファイルのパス。 |
| `labelsJson` | `string` | 必須 | ラベル定義 JSON。空文字で既定ラベルを使用。 |
| `confidence` | `double` | 必須 | 信頼度しきい値（`0.0`〜`1.0`）。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### labelsJson の JSON スキーマ

空文字の場合は既定ラベル（YOLO 系は COCO 80 クラス、Faster R-CNN は torchvision COCO 91 クラス）を使用します。カスタムラベルを指定する場合は以下のいずれかの形式を使用します。

```json
["person", "car", "dog"]
```

または、クラス ID からラベル名へのマップ:

```json
{"0":"person","1":"car","2":"dog"}
```

| 形式 | 型 | 説明 |
|---|---|---|
| 配列 | `string[]` | クラス ID 0 から順にラベル名を並べた配列 |
| マップ | `object` | キーをクラス ID（文字列または数値）、値をラベル名とするオブジェクト |

##### コールバック JSON スキーマ

成功時:

```json
[{ "label": "person", "score": 0.85, "x": 10, "y": 20, "w": 100, "h": 200 }]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `label` | `string` | 検出ラベル名 |
| `score` | `number` | 信頼度スコア（0.0〜1.0） |
| `x` | `number` | 検出矩形の左上 X 座標（元画像ピクセル） |
| `y` | `number` | 検出矩形の左上 Y 座標（元画像ピクセル） |
| `w` | `number` | 検出矩形の幅（元画像ピクセル） |
| `h` | `number` | 検出矩形の高さ（元画像ピクセル） |

失敗時:

```json
{"error":"エラーメッセージ"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

Windows は起動失敗時に `false`。**Android は受け付け次第 `true` を返す**。`callback` は呼び出し前に定義しておくこと。`modelPath` は有効な ONNX ファイルを指定。停止時は対となる `stopObjectDetect()` を呼び出すこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.startObjectDetect('onResult', '%APP%/models/yolov8n.onnx', '', 0.5);
if (!ok) console.error('startObjectDetect 失敗');
```


##### 備考

- `confidence`: 信頼度しきい値（0.0〜1.0）。このスコア以上の検出のみ返します。
- `modelPath` は ONNX モデルのパス（例: `%APP%/models/model.onnx`）。
- `startObjectDetect` の `callback(json)` は **3 フレーム連続で同一物体と判定された後、かつ検出ラベル・個数のシグネチャに変化があったとき** に呼ばれます（フレーム毎の連続通知ではありません）。
- 顔検出（`startFaceDetect`）と同時にはカメラを共有できません（排他運用）。
- 旧称 `yoloDetect*` / `getYoloDeviceInfo` / `setYoloGpuDevice` は **stub 環境でのみ存在する互換エイリアス**です。ネイティブ `JsObject` には存在しません。新規実装では `objectDetect*` / `getObjectDetectDeviceInfo` / `setObjectDetectGpuDevice` を使用してください。
#### bool stopObjectDetect()

Windows は動作中以降 `true`。

- **対応プラットフォーム**: Windows ○ / Android △
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

Windows は動作中以降 `true`。**Android は常に `true**。`startObjectDetect()` の後に対となるように呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.stopObjectDetect();
if (!ok) console.error('stopObjectDetect 失敗');
```

#### string objectDetectImage(string imagePath, string modelPath, string labelsJson, double confidence)

静止画を 1 回検出。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `imagePath` | `string` | 必須 | 文字列。 |
| `modelPath` | `string` | 必須 | ONNX モデルファイルのパス。 |
| `labelsJson` | `string` | 必須 | ラベル定義 JSON。空文字で既定ラベルを使用。 |
| `confidence` | `double` | 必須 | 信頼度しきい値（`0.0`〜`1.0`）。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### labelsJson の JSON スキーマ

空文字の場合は既定ラベル（YOLO 系は COCO 80 クラス、Faster R-CNN は torchvision COCO 91 クラス）を使用します。カスタムラベルを指定する場合は以下のいずれかの形式を使用します。

```json
["person", "car", "dog"]
```

または、クラス ID からラベル名へのマップ:

```json
{"0":"person","1":"car","2":"dog"}
```

| 形式 | 型 | 説明 |
|---|---|---|
| 配列 | `string[]` | クラス ID 0 から順にラベル名を並べた配列 |
| マップ | `object` | キーをクラス ID（文字列または数値）、値をラベル名とするオブジェクト |

##### 戻り値 JSON スキーマ

成功時:

```json
[{ "label": "person", "score": 0.85, "x": 10, "y": 20, "w": 100, "h": 200 }]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `label` | `string` | 検出ラベル名 |
| `score` | `number` | 信頼度スコア（0.0〜1.0） |
| `x` | `number` | 検出矩形の左上 X 座標（元画像ピクセル） |
| `y` | `number` | 検出矩形の左上 Y 座標（元画像ピクセル） |
| `w` | `number` | 検出矩形の幅（元画像ピクセル） |
| `h` | `number` | 検出矩形の高さ（元画像ピクセル） |

失敗時:

```json
{"error":"エラーメッセージ"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 備考

`imagePath` には `file://` URI も許容。結果 JSON を返す。`getObjectDetectDeviceInfo()` / `setObjectDetectGpuDevice()` でデバイスを確認・選択してから使うことを推奨

##### サンプル

```javascript
const result = await window.sticktv.objectDetectImage('', '%APP%/models/yolov8n.onnx', '', 0.5);
console.log(result);
```

#### string objectDetectBase64(string base64, string modelPath, string labelsJson, double confidence)

Base64（`data:` URL 可）画像を 1 回検出。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `base64` | `string` | 必須 | 文字列。 |
| `modelPath` | `string` | 必須 | ONNX モデルファイルのパス。 |
| `labelsJson` | `string` | 必須 | ラベル定義 JSON。空文字で既定ラベルを使用。 |
| `confidence` | `double` | 必須 | 信頼度しきい値（`0.0`〜`1.0`）。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |


##### labelsJson の JSON スキーマ

空文字の場合は既定ラベル（YOLO 系は COCO 80 クラス、Faster R-CNN は torchvision COCO 91 クラス）を使用します。カスタムラベルを指定する場合は以下のいずれかの形式を使用します。

```json
["person", "car", "dog"]
```

または、クラス ID からラベル名へのマップ:

```json
{"0":"person","1":"car","2":"dog"}
```

| 形式 | 型 | 説明 |
|---|---|---|
| 配列 | `string[]` | クラス ID 0 から順にラベル名を並べた配列 |
| マップ | `object` | キーをクラス ID（文字列または数値）、値をラベル名とするオブジェクト |

##### 戻り値 JSON スキーマ

成功時:

```json
[{ "label": "person", "score": 0.85, "x": 10, "y": 20, "w": 100, "h": 200 }]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `label` | `string` | 検出ラベル名 |
| `score` | `number` | 信頼度スコア（0.0〜1.0） |
| `x` | `number` | 検出矩形の左上 X 座標（元画像ピクセル） |
| `y` | `number` | 検出矩形の左上 Y 座標（元画像ピクセル） |
| `w` | `number` | 検出矩形の幅（元画像ピクセル） |
| `h` | `number` | 検出矩形の高さ（元画像ピクセル） |

失敗時:

```json
{"error":"エラーメッセージ"}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 備考

ファイル保存なし。`getObjectDetectDeviceInfo()` / `setObjectDetectGpuDevice()` でデバイスを確認・選択してから使うことを推奨

##### サンプル

```javascript
const result = await window.sticktv.objectDetectBase64('', '%APP%/models/yolov8n.onnx', '', 0.5);
console.log(result);
```

#### string getObjectDetectDeviceInfo()

Windows はプロバイダ/GPU 一覧 JSON。

- **対応プラットフォーム**: Windows ○ / Android △
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
{ "provider": "...", "deviceId": 0, "gpu": "GPU名",
  "adapters": [{ "id": 0, "name": "GPU名", "vramMB": 8128 }] }
```

| フィールド | 型 | 説明 |
|---|---|---|
| `provider` | `string` | 実行プロバイダー名 |
| `deviceId` | `number` | 使用中のデバイス ID |
| `gpu` | `string` | 使用中の GPU 名 |
| `adapters` | `object[]` | 利用可能なアダプター一覧 |
| `adapters[].id` | `number` | アダプター ID |
| `adapters[].name` | `string` | アダプター名 |
| `adapters[].vramMB` | `number` | 推定 VRAM（MB） |

`getObjectDetectDeviceInfo()` は Android では CPU 固定の固定 JSON を返します。 |
##### 前提・後続 API

Windows はプロバイダ/GPU 一覧 JSON。**Android は CPU 固定の固定 JSON**。`objectDetectImage()` / `objectDetectBase64()` の前に確認してから、`setObjectDetectGpuDevice()` を使うことを推奨

##### サンプル

```javascript
const result = await window.sticktv.getObjectDetectDeviceInfo();
console.log(result);
```

#### bool setObjectDetectGpuDevice(int deviceId)

Android は常に `false`（CPU 固定）。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `deviceId` | `int` | 必須 | 数値。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

**Android は常に `false`**（CPU 固定）。`getObjectDetectDeviceInfo()` 後に、`objectDetectImage()` / `objectDetectBase64()` 前に呼び出すことを推奨

##### サンプル

```javascript
const ok = await window.sticktv.setObjectDetectGpuDevice(0);
if (!ok) console.error('setObjectDetectGpuDevice 失敗');
```


### BLE・SwitchBot

ローカル BLE（GATT）で SwitchBot デバイスを制御します。`address` は `aa:bb:cc:dd:ee:ff` 形式の MAC アドレス。

#### bool bleScanStart(int seconds)

`seconds` 秒間スキャン。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `seconds` | `int` | 必須 | 秒数。`0` 以下の場合は手動停止まで継続。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

`seconds` 秒間スキャン。失敗時 `false`。スキャン後は必ず `bleScanResult()` を呼び出して結果を取得すること

##### サンプル

```javascript
const ok = await window.sticktv.bleScanStart(5);
if (!ok) console.error('bleScanStart 失敗');
```

#### bool bleScanStop()

`bleScanStart()` 中のスキャンを停止。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

`bleScanStart()` 中のスキャンを停止。通常はスキャン時間が経過しても結果を取るため `bleScanResult()` を呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.bleScanStop();
if (!ok) console.error('bleScanStop 失敗');
```

#### string bleScanResult()

`[{"address":"...","name":"...","rssi":-52, "deviceType":"..."}, ...]`。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
[{"address":"aa:bb:cc:dd:ee:ff","name":"SwitchBot","rssi":-52,"deviceType":"..."}]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | デバイスの MAC アドレス |
| `name` | `string` | デバイス名（取得できない場合は空文字） |
| `rssi` | `number` | 信号強度（dBm） |
| `deviceType` | `string` | SwitchBot デバイス種別 |
##### 前提・後続 API

`[{"address":"...","name":"...","rssi":-52, "deviceType":"..."}, ...]`。なければ `"[]"`。`bleScanStart()` 後に必ず呼び出すこと。取得した `address` をもとに各種 `switchBot*` を呼び出す。スキャン完了までに時間がかかることがあるため、`bleScanStart(seconds)` の完了後、1 秒程度の間隔を空けてから `bleScanResult()` を呼び出し、空配列の場合は数回に分けて再取得することを推奨する

##### サンプル

```javascript
const result = await window.sticktv.bleScanResult();
console.log(result);
```

#### bool switchBotOn(string address)

Bot を ON（押し込んだ状態を保持）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

Bot を ON（押し込んだ状態を保持）。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.switchBotOn('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('switchBotOn 失敗');
```

#### bool switchBotOff(string address)

Bot を OFF（押し戻しを保持）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

Bot を OFF（押し戻しを保持）。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.switchBotOff('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('switchBotOff 失敗');
```

#### bool switchBotPress(string address)

押してすぐ戻す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

押してすぐ戻す。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.switchBotPress('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('switchBotPress 失敗');
```

#### bool switchBotPlugMiniOn(string address)

プラグミニ ON。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

プラグミニ ON。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.switchBotPlugMiniOn('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('switchBotPlugMiniOn 失敗');
```

#### bool switchBotPlugMiniOff(string address)

プラグミニ OFF。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

プラグミニ OFF。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.switchBotPlugMiniOff('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('switchBotPlugMiniOff 失敗');
```

#### bool switchBotPlugMiniToggle(string address)

プラグミニ トグル。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

プラグミニ トグル。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.switchBotPlugMiniToggle('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('switchBotPlugMiniToggle 失敗');
```

#### bool setSwitchBotRemoteCallback(string callback)

Remote Button 等のイベントを `callback(json)` で通知。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### コールバック JSON スキーマ

```json
{"event":"remoteButtonPressed","mac":"AA:BB:CC:DD:EE:FF","button":"upper|lower","source":"sniffer|peripheral","timestamp":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `event` | `string` | イベント名 |
| `mac` | `string` | リモートボタンの MAC アドレス |
| `button` | `string` | 押されたボタン（`"upper"` / `"lower"`） |
| `source` | `string` | 検出ソース（`"sniffer"` / `"peripheral"`） |
| `timestamp` | `string` | イベント発生時刻 |
##### 前提・後続 API

Remote Button 等のイベントを `callback(json)` で通知。`callback` は呼び出し前に定義しておくこと。受信を開始する前に呼び出すこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.setSwitchBotRemoteCallback('onResult');
if (!ok) console.error('setSwitchBotRemoteCallback 失敗');
```


##### 備考

- Windows は Windows 10 以降 + Bluetooth LE アダプタ、Android は Bluetooth LE 対応端末が必要。Android 12 (API 31) 以降では `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT` のランタイム権限が必要です（起動時に要求）。
- `setSwitchBotRemoteCallback` のコールバックは JSON 文字列 1 引数。Remote Button 押下は `{"event":"remoteButtonPressed","mac":"...","button":"upper|lower","source":"sniffer|peripheral","timestamp":"..."}` 形式で通知されます。
- `switchBotGetDeviceInfo` の主なフィールド: `Address`, `Name`, `Rssi`, `DeviceType`, `State`, `PowerW`, `Overload`。
- 制御対象のデバイスやファームウェアによっては暗号化が必要です。
#### string switchBotGetDeviceInfo(string address)

デバイス詳細を JSON で返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
{"Address":"AA:BB:CC:DD:EE:FF","Name":"SwitchBot","Rssi":-52,"DeviceType":"Bot","State":true,"PowerW":0.0,"Overload":false}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `Address` | `string` | MAC アドレス |
| `Name` | `string` | デバイス名 |
| `Rssi` | `number` | 信号強度 |
| `DeviceType` | `string` | デバイス種別 |
| `State` | `boolean` / `string` | デバイス状態 |
| `PowerW` | `number` | 消費電力（W） |
| `Overload` | `boolean` | 過負荷状態 |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

デバイス詳細を JSON で返す。失敗時は `{"error":"..."}`。呼び出し前に `bleScanStart()` → `bleScanResult()` で対象 `address` を取得しておくこと

##### サンプル

```javascript
const result = await window.sticktv.switchBotGetDeviceInfo('AA:BB:CC:DD:EE:FF');
console.log(result);
```


#### bool usbSerialScanStart(int seconds)

NUS デバイスを `seconds` 秒間スキャン。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `seconds` | `int` | 必須 | 秒数。`0` 以下の場合は手動停止まで継続。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

NUS デバイスを `seconds` 秒間スキャン。失敗時 `false`。スキャン後は必ず `usbSerialScanResult()` を呼び出して結果を取得すること

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialScanStart(5);
if (!ok) console.error('usbSerialScanStart 失敗');
```

#### bool usbSerialScanStop()

`usbSerialScanStart()` 中のスキャンを停止。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

`usbSerialScanStart()` 中のスキャンを停止。通常はスキャン時間が経過しても結果を取るため `usbSerialScanResult()` を呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialScanStop();
if (!ok) console.error('usbSerialScanStop 失敗');
```

#### string usbSerialScanResult()

`[{"address":"...","name":"...","rssi":-52}, ...]`。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

`usbSerialScanResult()` の配列要素:

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | MAC アドレス |
| `name` | `string` | デバイス名 |
| `rssi` | `number` | 信号強度 |
##### 前提・後続 API

`[{"address":"...","name":"...","rssi":-52}, ...]`。なければ `"[]"`。`usbSerialScanStart()` 後に必ず呼び出すこと。取得した `address` をもとに `usbSerialConnect()` を行う

##### サンプル

```javascript
const result = await window.sticktv.usbSerialScanResult();
console.log(result);
```

#### bool usbSerialConnect(string address)

NUS デバイスに接続。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

NUS デバイスに接続。呼び出し前に `usbSerialScanStart()` → `usbSerialScanResult()` で対象 `address` を取得しておくこと。接続後に `usbSerialWrite()` / `usbSerialSetReadCallback()` / `usbSerialSetEventCallback()` を使う

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialConnect('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('usbSerialConnect 失敗');
```


##### 備考

- NUS Service UUID: `6E400001-B5A3-F393-E0A9-E50E24DCCA9E`
- RX Characteristic UUID（送信先）: `6E400002-B5A3-F393-E0A9-E50E24DCCA9E`
- TX Characteristic UUID（受信元）: `6E400003-B5A3-F393-E0A9-E50E24DCCA9E`
- `usbSerialConnect` で接続を確立し、明示的に `usbSerialDisconnect` を呼ぶまで維持します。
#### bool usbSerialDisconnect(string address)

接続を切断。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

接続を切断。`usbSerialConnect()` の後に対となるように呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialDisconnect('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('usbSerialDisconnect 失敗');
```

#### bool usbSerialWrite(string address, string base64Data)

Base64 データを RX characteristic へ Write。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |
| `base64Data` | `string` | 必須 | Base64 エンコード済みデータ。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

Base64 データを RX characteristic へ Write。`usbSerialConnect()` 成功後に呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialWrite('AA:BB:CC:DD:EE:FF', btoa('hello'));
if (!ok) console.error('usbSerialWrite 失敗');
```

#### bool usbSerialSetReadCallback(string address, string callback)

TX Notify 受信時に `callback(json)` を実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### コールバック JSON スキーマ

```json
{"address":"...","base64":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | 送信元セントラルの MAC アドレス |
| `base64` | `string` | 受信データ（Base64 エンコード） |
##### 前提・後続 API

TX Notify 受信時に `callback(json)` を実行。`callback` は呼び出し前に定義しておくこと。`usbSerialConnect()` 後に呼び出すことを推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.usbSerialSetReadCallback('AA:BB:CC:DD:EE:FF', 'onResult');
if (!ok) console.error('usbSerialSetReadCallback 失敗');
```

#### bool usbSerialSetEventCallback(string address, string callback)

接続/切断/エラー時に `callback(json)` を実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### コールバック JSON スキーマ

```json
{"address":"...","event":"connected|disconnected|error","message":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | 対象デバイスの MAC アドレス |
| `event` | `string` | `"connected"` / `"disconnected"` / `"error"` |
| `message` | `string` | イベント詳細メッセージ |
##### 前提・後続 API

接続/切断/エラー時に `callback(json)` を実行。`callback` は呼び出し前に定義しておくこと。`usbSerialConnect()` 前または直後に設定しておくことを推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.usbSerialSetEventCallback('AA:BB:CC:DD:EE:FF', 'onResult');
if (!ok) console.error('usbSerialSetEventCallback 失敗');
```

#### bool usbSerialIsConnected(string address)

接続状態を確認。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

接続状態を確認。`usbSerialConnect()` 後に `usbSerialWrite()` 等を呼び出す前に確認することが多い

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialIsConnected('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('usbSerialIsConnected 失敗');
```


備考:

- NUS Service UUID: `6E400001-B5A3-F393-E0A9-E50E24DCCA9E`
- RX Characteristic UUID（送信先）: `6E400002-B5A3-F393-E0A9-E50E24DCCA9E`
- TX Characteristic UUID（受信元）: `6E400003-B5A3-F393-E0A9-E50E24DCCA9E`
#### bool usbSerialStartPeripheral()

NUS サービスを登録し BLE アドバタイズを開始。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

NUS サービスを登録し BLE アドバタイズを開始。既に開始済みの場合は `false`。開始後に `usbSerialGetPeripheralInfo()` / `usbSerialSetPeripheralReadCallback()` / `usbSerialSetPeripheralEventCallback()` を使い、通信開始後は `usbSerialPeripheralWrite()` を使う。停止時は `usbSerialStopPeripheral()` を呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialStartPeripheral();
if (!ok) console.error('usbSerialStartPeripheral 失敗');
```


##### 備考

- 使用する UUID は Central（セントラル）側と同じ NUS UUID です。
- Android では `BLUETOOTH_ADVERTISE` 権限（Android 12 以降はランタイム権限）が必要です。
- Windows では Bluetooth LE アダプタが必要です。アドバタイズ名は PC 名（`Environment.MachineName`）を使用します。
#### bool usbSerialStopPeripheral()

ペリフェラル停止。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

ペリフェラル停止。接続中のセントラルも切断する。`usbSerialStartPeripheral()` の後に対となるように呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialStopPeripheral();
if (!ok) console.error('usbSerialStopPeripheral 失敗');
```

#### string usbSerialGetPeripheralInfo()

`{"address":"...","name":"...","advertising":true/false,"serviceUuid":"..."}` 形式。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
{"address":"...","name":"...","advertising":true,"serviceUuid":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | 自機 MAC アドレス。取得できない場合は空文字 |
| `name` | `string` | アドバタイズ名 |
| `advertising` | `boolean` | アドバタイズ中の場合 `true` |
| `serviceUuid` | `string` | NUS サービス UUID |
##### 前提・後続 API

`{"address":"...","name":"...","advertising":true/false,"serviceUuid":"..."}` 形式。MAC アドレス取得できない場合は `"address":""`。`usbSerialStartPeripheral()` 後に呼び出して自機の MAC やアドバタイズ状態を確認すること

##### サンプル

```javascript
const result = await window.sticktv.usbSerialGetPeripheralInfo();
console.log(result);
```

#### bool usbSerialIsPeripheralConnected(string address)

指定 MAC のセントラルが接続中か確認。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

指定 MAC のセントラルが接続中か確認。空文字なら接続中があれば `true`。`usbSerialStartPeripheral()` 後に `usbSerialPeripheralWrite()` の前に確認することが多い

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialIsPeripheralConnected('AA:BB:CC:DD:EE:FF');
if (!ok) console.error('usbSerialIsPeripheralConnected 失敗');
```

#### bool usbSerialPeripheralWrite(string address, string base64Data)

指定セントラルへ TX Notify で Base64 データを送信。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |
| `base64Data` | `string` | 必須 | Base64 エンコード済みデータ。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

指定セントラルへ TX Notify で Base64 データを送信。空文字なら最初に見つかった接続先へ送信。`usbSerialStartPeripheral()` 実行後、セントラルから接続された状態で呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.usbSerialPeripheralWrite('AA:BB:CC:DD:EE:FF', btoa('hello'));
if (!ok) console.error('usbSerialPeripheralWrite 失敗');
```

#### bool usbSerialSetPeripheralReadCallback(string address, string callback)

RX 受信時に `callback(json)` を実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### コールバック JSON スキーマ

```json
{"address":"...","base64":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | 送信元セントラルの MAC アドレス |
| `base64` | `string` | 受信データ（Base64 エンコード） |
##### 前提・後続 API

RX 受信時に `callback(json)` を実行。`address` は無視され全セントラルで共有。`callback` は呼び出し前に定義しておくこと。`usbSerialStartPeripheral()` 後に設定しておくことを推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.usbSerialSetPeripheralReadCallback('AA:BB:CC:DD:EE:FF', 'onResult');
if (!ok) console.error('usbSerialSetPeripheralReadCallback 失敗');
```

#### bool usbSerialSetPeripheralEventCallback(string address, string callback)

接続/切断/エラー時に `callback(json)` を実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `address` | `string` | 必須 | MAC アドレス（`aa:bb:cc:dd:ee:ff` 形式）またはデバイス識別子。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### コールバック JSON スキーマ

```json
{"address":"...","event":"connected|disconnected|error","message":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `address` | `string` | 対象デバイスの MAC アドレス |
| `event` | `string` | `"connected"` / `"disconnected"` / `"error"` |
| `message` | `string` | イベント詳細メッセージ |
##### 前提・後続 API

接続/切断/エラー時に `callback(json)` を実行。`address` は無視され全セントラルで共有。`callback` は呼び出し前に定義しておくこと。`usbSerialStartPeripheral()` 後に設定しておくことを推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.usbSerialSetPeripheralEventCallback('AA:BB:CC:DD:EE:FF', 'onResult');
if (!ok) console.error('usbSerialSetPeripheralEventCallback 失敗');
```


### プロセス間コマンド通信（Windows / Android 版）

同一 PC / 同一 LAN 内の複数 `sticktv.exe` プロセス間、同一 LAN 内の複数 Android 端末間、または BLE UART（NUS）接続先間で、一対一コマンド通信を行います。
メッセージは「4 バイト長さプレフィックス（little-endian）+ UTF-8 JSON 本文」でやり取りされます。
BLE UART を使う場合は、事前に `usbSerialConnect(mac)` で接続しておき、`target` に `"ble:<MAC>"` を指定します。
また、ローカル端末を NUS ペリフェラルとして動作させ（`usbSerialStartPeripheral()`）、リモートのセントラルから接続してもらうことでも通信できます。この場合も `target` に `"ble:<MAC>"` を指定すると、ネイティブ側でセントラル側接続とペリフェラル側接続のどちらかを自動的に選択して送信します。

#### void startCommandServer(int port, string callback)

指定ポートで待ち受け開始。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `port` | `int` | 必須 | 数値。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### コールバック JSON スキーマ

```json
{ "id": "...", "cmd": "foo", "payload": "...", "from": "192.168.1.10:52345" }
```

| フィールド | 型 | 説明 |
|---|---|---|
| `id` | `string` | 送信側のコマンド ID |
| `cmd` | `string` | コマンド名 |
| `payload` | `any` | ペイロード |
| `from` | `string` | 送信元の `"ip:port"` または `"ble:<MAC>"` |
##### 前提・後続 API

指定ポートで待ち受け開始。受信時 `callback(commandJson)` を実行。`callback` は呼び出し前に定義しておくこと。受信・応答を行うには先に呼び出すこと。停止時は `stopCommandServer()` を使うこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.startCommandServer(0, 'onResult');
```

#### void stopCommandServer()

待ち受けを停止し、接続を解放。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

待ち受けを停止し、接続を解放。`startCommandServer()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.stopCommandServer();
```

#### string sendCommand(string target, string commandJson, int timeoutMs)

`target` は `"ip:port"` または `"ble:<MAC>"` 形式。 **Windows 版は `Task<T>` のため JS 側で `await` が必要**。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `target` | `string` | 必須 | 接続先。`"ip:port"` または `"ble:<MAC>"` 形式。 |
| `commandJson` | `string` | 必須 | コマンド JSON 文字列。 |
| `timeoutMs` | `int` | 必須 | タイムアウト時間（ミリ秒）。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### commandJson の JSON スキーマ

```json
{ "id": "...", "cmd": "foo", "payload": "..." }
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `id` | `string` | 必須 | コマンドを一意に識別する ID。応答紐付けに使用 |
| `cmd` | `string` | 必須 | コマンド名 |
| `payload` | `any` | 任意 | コマンドに付随するデータ。文字列、オブジェクト、JSON 文字列等 |

##### responseJson の JSON スキーマ

```json
{ "id": "...", "replyTo": "受信コマンドのid", "payload": "..." }
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `id` | `string` | 必須 | この応答を一意に識別する ID |
| `replyTo` | `string` | 必須 | 受信コマンドの `id` |
| `payload` | `any` | 任意 | 応答データ |
##### 前提・後続 API

`target` は `"ip:port"` または `"ble:<MAC>"` 形式。応答 JSON を返す。**Windows 版は `Task<string>` なので JS 側で `await` が必要**。BLE 経由で送信する場合は事前に `usbSerialConnect(mac)` または `usbSerialStartPeripheral()` で接続しておくこと

##### サンプル

```javascript
const result = await window.sticktv.sendCommand('192.168.1.5:9001', JSON.stringify({ cmd: 'ping' }), 5000);
console.log(result);
```

#### void asyncSendCommand(string target, string commandJson, string callback, int timeoutMs)

非同期版。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `target` | `string` | 必須 | 接続先。`"ip:port"` または `"ble:<MAC>"` 形式。 |
| `commandJson` | `string` | 必須 | コマンド JSON 文字列。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |
| `timeoutMs` | `int` | 必須 | タイムアウト時間（ミリ秒）。 |


##### commandJson の JSON スキーマ

```json
{ "id": "...", "cmd": "foo", "payload": "..." }
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `id` | `string` | 必須 | コマンドを一意に識別する ID。応答紐付けに使用 |
| `cmd` | `string` | 必須 | コマンド名 |
| `payload` | `any` | 任意 | コマンドに付随するデータ。文字列、オブジェクト、JSON 文字列等 |

##### コールバック JSON スキーマ

```json
{ "id": "...", "replyTo": "受信コマンドのid", "payload": "..." }
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `id` | `string` | 必須 | この応答を一意に識別する ID |
| `replyTo` | `string` | 必須 | 受信コマンドの `id` |
| `payload` | `any` | 任意 | 応答データ |
##### 前提・後続 API

非同期版。完了時 `callback(responseJson)` を実行。`callback` は呼び出し前に定義しておくこと。BLE 経由の場合は事前に `usbSerialConnect(mac)` / `usbSerialStartPeripheral()` で接続しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncSendCommand('192.168.1.5:9001', JSON.stringify({ cmd: 'ping' }), 'onResult', 5000);
```

#### void sendCommandReply(string replyTo, string responseJson)

受信コマンドの `id` を `replyTo` に指定して応答を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `replyTo` | `string` | 必須 | 受信コマンドの `id`。 |
| `responseJson` | `string` | 必須 | 文字列。 |


##### responseJson の JSON スキーマ

```json
{ "id": "...", "replyTo": "受信コマンドのid", "payload": "..." }
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `id` | `string` | 必須 | この応答を一意に識別する ID |
| `replyTo` | `string` | 必須 | 受信コマンドの `id` |
| `payload` | `any` | 任意 | 応答データ |
##### 前提・後続 API

受信コマンドの `id` を `replyTo` に指定して応答を返す。`startCommandServer()` でコマンドを受信した後に呼び出すこと

##### サンプル

```javascript
window.sticktv.sendCommandReply(cmd.id, '');
```


### 音量・画面・システム

#### void setVolume(int volume)

0〜100。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `volume` | `int` | 必須 | 数値。 |

##### 前提・後続 API

0〜100。必要に応じて `getVolume()` / `getDefaultVolume()` 後に呼び出すこと

##### サンプル

```javascript
window.sticktv.setVolume(0);
```

#### int getVolume()

現在の音量を取得（取得失敗時 `-1`）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `int`

##### 戻り値

| 型 | 内容 |
|---|---|
| `int` | 整数値。失敗時 `-1`（但し `printPngUrl` 等の例外あり）。 |

##### 前提・後続 API

現在の音量を取得（取得失敗時 `-1`）。取得後に `setVolume()` を調整することが多い

##### サンプル

```javascript
const result = await window.sticktv.getVolume();
console.log(result);
```

#### int getDefaultVolume()

既定音量を取得。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `int`

##### 戻り値

| 型 | 内容 |
|---|---|
| `int` | 整数値。失敗時 `-1`（但し `printPngUrl` 等の例外あり）。 |

##### 前提・後続 API

既定音量を取得。取得後に `setVolume()` を調整することがある

##### サンプル

```javascript
const result = await window.sticktv.getDefaultVolume();
console.log(result);
```

#### int getCallVolume()

Windows は常に `0`（未対応）。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `int`

##### 戻り値

| 型 | 内容 |
|---|---|
| `int` | 整数値。失敗時 `-1`（但し `printPngUrl` 等の例外あり）。 |

##### 備考

**Windows は常に `0`**（未対応）

##### サンプル

```javascript
const result = await window.sticktv.getCallVolume();
console.log(result);
```

#### int getTalkVolume()

Windows は常に `0`（未対応）。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `int`

##### 戻り値

| 型 | 内容 |
|---|---|
| `int` | 整数値。失敗時 `-1`（但し `printPngUrl` 等の例外あり）。 |

##### 備考

**Windows は常に `0`**（未対応）

##### サンプル

```javascript
const result = await window.sticktv.getTalkVolume();
console.log(result);
```

#### void setSpeakerPhone(bool mode)

Windows 未対応。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `mode` | `bool` | 必須 | 真偽値。 |

##### 備考

Android では通話音声のスピーカー出力を切り替える

##### サンプル

```javascript
window.sticktv.setSpeakerPhone(true);
```

#### void setKeepScreen(bool on)

画面の常時点灯を有効/無効にする。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `on` | `bool` | 必須 | 真偽値。 |

##### 備考

解除時は `false` を指定するか、`setKeepScreenBacklight(false)` を使う

##### サンプル

```javascript
window.sticktv.setKeepScreen(true);
```

#### void setKeepScreenBacklight(bool onOff)

`setKeepScreen` と同等。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `onOff` | `bool` | 必須 | 真偽値。 |

##### 備考

常時点灯を有効/無効にする

##### サンプル

```javascript
window.sticktv.setKeepScreenBacklight(true);
```

#### void setBacklight(float value)

Windows は未実装（何もしない）。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `value` | `float` | 必須 | 数値。 |

##### 前提・後続 API

**Windows は未実装（何もしない）**。Android は輝度 0.0〜1.0 を設定。設定前に `getBacklight()` / `getScreenBrightness()` で現在値を確認することがある

##### サンプル

```javascript
window.sticktv.setBacklight(1.0);
```

#### float getBacklight()

Windows は未対応で常に `0`（ドメイン拒否時も `0`）。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `float`

##### 戻り値

| 型 | 内容 |
|---|---|
| `float` | 浮動小数点数。Windows 未対応 API では `0`。 |

##### 前提・後続 API

**Windows は未対応で常に `0`**（ドメイン拒否時も `0`）。Android は現在の輝度（0.0〜1.0）。取得後に `setBacklight()` を使うことがある

##### サンプル

```javascript
const value = await window.sticktv.getBacklight();
```

#### float getScreenBrightness()

Windows は未対応で常に `0`（ドメイン拒否時も `0`）。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `float`

##### 戻り値

| 型 | 内容 |
|---|---|
| `float` | 浮動小数点数。Windows 未対応 API では `0`。 |

##### 前提・後続 API

**Windows は未対応で常に `0`**（ドメイン拒否時も `0`）。Android は現在の輝度。取得後に `setScreenBrightness()` を使うことがある

##### サンプル

```javascript
const value = await window.sticktv.getScreenBrightness();
```

#### void setScreenBrightness(float val)

Windows 未実装。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `val` | `float` | 必須 | 数値。 |

##### 前提・後続 API

Windows 未実装。Android は輝度を設定。`getScreenBrightness()` 後に呼び出すことがある

##### サンプル

```javascript
window.sticktv.setScreenBrightness(1.0);
```

#### void showLoading()

ローディング表示を開始。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

ローディング表示を開始。長時間処理の前に呼び出し、完了後に `hideLoading()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.showLoading();
```

#### void hideLoading()

ローディング非表示。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

ローディング非表示。`showLoading()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.hideLoading();
```

#### void setZoomEnable(bool enable)

`false` でズーム解除（Windows は ZoomFactor を 1.0 にリセット）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `enable` | `bool` | 必須 | 真偽値。 |

##### 前提・後続 API

`false` でズーム解除（Windows は ZoomFactor を 1.0 にリセット）。通常はページ読み込み後に呼び出す

##### サンプル

```javascript
window.sticktv.setZoomEnable(true);
```

#### void showTaskbar(bool show)

Windows 専用。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `show` | `bool` | 必須 | 真偽値。 |

##### 備考

タスクバー表示/非表示を切り替える

##### サンプル

```javascript
window.sticktv.showTaskbar(true);
```

#### void showTopmost(bool topmost)

Windows 専用。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `topmost` | `bool` | 必須 | 真偽値。 |

##### 備考

最前面表示の切り替え

##### サンプル

```javascript
window.sticktv.showTopmost(true);
```

#### void startLockTask()

キオスク（ロックタスク）開始。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 前提・後続 API

キオスク（ロックタスク）開始。Windows 未対応。終了時は `stopLockTask()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.startLockTask();
```

#### void stopLockTask()

キオスク解除。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 前提・後続 API

キオスク解除。Windows 未対応。`startLockTask()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.stopLockTask();
```


---

### IME・キーボード・プロセス（Windows 専用）

| 関数名 | シグネチャ | 戻り値 | 備考 |
|---|---|---|---|
| `sendKey` | `void sendKey(int code)` | `void` | 仮想キーコードを送信。アクティブな入力先がある状態で呼び出すこと |
| `showIme` | `void showIme(bool mode)` | `void` | Windows タッチキーボードの表示/非表示を切り替える。表示後は `showIme(false)` で閉じることが多い |
| `setKeyboardLayout` | `void setKeyboardLayout(string locale)` | `void` | カルチャ名（例: `"ja-JP"`）から KLID を取得してレイアウト変更。切り替え後にキー入力する場合は、入力先がアクティブになってから呼び出すこと |
| `killProcess` | `void killProcess(string processName)` | `void` | 指定プロセス名のプロセスを終了。影響範囲を確認してから呼び出すこと |


これらは Windows 版のみの API です（Android 版には存在しません）。

---

### TTS / STT

#### void startTTS(string talktext)

Windows は System.Speech（日本語音声を優先選択）、Android は TTS エンジンで発話を開始。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `talktext` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

Windows は System.Speech（日本語音声を優先選択）、Android は TTS エンジンで発話を開始。連続して発話する場合は `stopTTS()` 後に次の `startTTS()` を呼び出すことを推奨

##### サンプル

```javascript
window.sticktv.startTTS('');
```

#### void stopTTS()

発話を停止。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

発話を停止。`startTTS()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.stopTTS();
```

#### void startSTT(string sttCallback, int interval)

音声認識を開始。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `sttCallback` | `string` | 必須 | 文字列。 |
| `interval` | `int` | 必須 | 数値。 |

##### 前提・後続 API

音声認識を開始。認識結果は `sttCallback('音声認識:...')`、エラーは `sttCallback('音声認識エラー:...')` で通知。`sttCallback` は呼び出し前に定義しておくこと。Windows は `System.Speech.Recognition` を使用。停止時は `stopSTT()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.startSTT('', 0);
```

#### void stopSTT()

音声認識を停止。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

音声認識を停止。`startSTT()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.stopSTT();
```


備考:

- Windows 版は `System.Speech.Recognition.SpeechRecognitionEngine` を使用し、マイク入力を既定音声入力デバイスから取得します。日本語認識を行うには、Windows に日本語音声認識言語パックがインストールされている必要があります。
- Windows 版は `DictationGrammar` を使用した自由文認識です。特定コマンドに絞りたい場合は、JavaScript 側で認識結果をフィルタリングしてください。

---

### デバイス情報

#### string getIMEI()

Windows は MAC アドレスを返す（IMEI の代替）。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

Android は端末識別子、IMEI が取得できない場合は MAC アドレス等の代替値。端末識別が必要な場合は `getMacAddress()` / `getDeviceId()` と併用して確認することがある

##### サンプル

```javascript
const result = await window.sticktv.getIMEI();
console.log(result);
```

#### string getMacAddress()

無線 LAN 優先、次に有線 LAN。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

端末識別に使用されることが多い

##### サンプル

```javascript
const result = await window.sticktv.getMacAddress();
console.log(result);
```

#### string getUniqid()

Windows は MAC アドレス。

- **対応プラットフォーム**: Windows △ / Android △
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

Android は端末固有のデバイス ID。端末識別に使用されることが多い

##### サンプル

```javascript
const result = await window.sticktv.getUniqid();
console.log(result);
```

#### string getDeviceId()

端末識別子を返す（Windows は MAC アドレス）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

端末を一意に特定する際に `getMacAddress()` や `getIMEI()` と併用されることがある

##### サンプル

```javascript
const result = await window.sticktv.getDeviceId();
console.log(result);
```

#### string getWebViewSize()

WebView の実サイズを `"幅x高さ"` で返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

WebView の実サイズを `"幅x高さ"` で返す。UI レイアウト調整の前に確認することがある

##### サンプル

```javascript
const result = await window.sticktv.getWebViewSize();
console.log(result);
```

#### string getWebviewName()

固定値 `"WebView2"`。

- **対応プラットフォーム**: Windows ○ / Android ×
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

**固定値 `"WebView2"`**。Windows 専用（Android に存在しない）。プラットフォーム判定の前に呼び出すことがある

##### サンプル

```javascript
const result = await window.sticktv.getWebviewName();
console.log(result);
```

#### string getFcmToken()

Windows は空文字（未対応）。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

Windows は**空文字**（未対応）。Android は FCM トークンを返す。プッシュ通知連携の前に取得しておくこと

##### サンプル

```javascript
const result = await window.sticktv.getFcmToken();
console.log(result);
```

#### bool useBackKey()

Windows は常に `false`。

- **対応プラットフォーム**: Windows △ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 備考

Android のハードウェアバックキー制御に関連する設定値を返す

##### サンプル

```javascript
const ok = await window.sticktv.useBackKey();
if (!ok) console.error('useBackKey 失敗');
```


---

### その他・互換 API

#### void showToast(string mes)

Windows はコンソールに出力、Android はトースト表示。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `mes` | `string` | 必須 | 文字列。 |

##### 備考

ユーザーへの軽微な通知用途

##### サンプル

```javascript
window.sticktv.showToast('');
```

#### void callbackTest(string mes, string callback)

両プラットフォームとも `callback` を実行せず、ログやコンソールに `mes` / `callback` を出力するデバッグ用 API。

- **対応プラットフォーム**: Windows ○ / Android △
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `mes` | `string` | 必須 | 文字列。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 備考

本番ロジックでは使用しないこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.callbackTest('', 'onResult');
```

#### int execPackage(string packageName, string className, string action, string uri, string extra, bool newTask)

Windows は `uri` を `Process.Start` で開く（`0`）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `int`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `packageName` | `string` | 必須 | 文字列。 |
| `className` | `string` | 必須 | 文字列。 |
| `action` | `string` | 必須 | 文字列。 |
| `uri` | `string` | 必須 | 文字列。 |
| `extra` | `string` | 必須 | 文字列。 |
| `newTask` | `bool` | 必須 | 真偽値。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `int` | 整数値。失敗時 `-1`（但し `printPngUrl` 等の例外あり）。 |

##### 備考

Android はインテントでアプリを起動。`newTask` で新しいタスク起動を制御。起動したアプリの結果を後続処理で使う場合は、別途そのアプリからのコールバックやファイル連携を検討すること

##### サンプル

```javascript
const result = await window.sticktv.execPackage('', '', '', '', '', true);
console.log(result);
```

#### string execBin(string cmd)

コマンドを実行して標準出力または標準エラーを返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `cmd` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 備考

Windows はタイムアウト 30 秒。実行結果を後続で処理する場合は戻り値を確認すること

##### サンプル

```javascript
const result = await window.sticktv.execBin('');
console.log(result);
```


備考:

- Windows 版は `cmd` を先頭トークン（実行ファイル）と残り（引数）に分割して直接起動します。`cmd.exe /c "dir /b"` のように明示的にシェルを指定することも可能です。
- タイムアウトは 30 秒です。長時間コマンドは `execPackage` で別プロセスを起動するか、別途検討してください。
- 任意コマンド実行 API は強力なため、許可ドメインの管理と実行環境のアクセス制御に注意してください。
- **命名の注意**: 歴史的経緯で `evalSubFrameWindow`（サブフレーム / オーバーレイ）と `evalSubWindow`（独立ウィンドウ）という似た名前の API が存在します。対象を開いた API と対になる eval API を使用してください。

#### void setLanguage(string lang)

Windows のみ存在し未実装（何もしない）。

- **対応プラットフォーム**: Windows × / Android ×
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `lang` | `string` | 必須 | 文字列。 |

##### 備考

後続の多言語処理には影響しない

##### サンプル

```javascript
window.sticktv.setLanguage('');
```

#### void optionsMenu()

Windows のみ存在し未実装。

- **対応プラットフォーム**: Windows × / Android ×
- **戻り値**: `void`

##### 備考

呼び出しても何も起きない

##### サンプル

```javascript
window.sticktv.optionsMenu();
```

#### void hideNavigationBar()

Windows のみ存在し未実装。

- **対応プラットフォーム**: Windows × / Android ×
- **戻り値**: `void`

##### 備考

呼び出しても何も起きない

##### サンプル

```javascript
window.sticktv.hideNavigationBar();
```

#### void setHandSignCallback(string callback)

Android のみ。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 前提・後続 API

**Android のみ**。ハンドサイン検出結果を `callback(json)` で通知。`callback` は呼び出し前に定義しておくこと。`openHandSignWindow()` 前に設定しておくことを推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.setHandSignCallback('onResult');
```

#### void openHandsignWindow(object activity)

Android のみ。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `activity` | `object` | 必須 | オブジェクト。JS からは文字列/オブジェクトを渡す。 |

##### 備考

ハンドサイン用サブウィンドウを表示。ただし JavaScript 側から MainActivity インスタンスを渡せないため、実質 `openHandSignWindow()` を使ってください

##### サンプル

```javascript
window.sticktv.openHandsignWindow('');
```

#### void closeHandsignWindow()

Android のみ。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 備考

`openHandsignWindow()` / `openHandSignWindow()` で開いたハンドサイン用ウィンドウを閉じる

##### サンプル

```javascript
window.sticktv.closeHandsignWindow();
```

#### void openHandSignWindow()

Android のみ。

- **対応プラットフォーム**: Windows × / Android ○
- **戻り値**: `void`

##### 前提・後続 API

**Android のみ**。ハンドサイン用サブウィンドウを表示（`MainActivity` 自身を渡して開く実用版）。必要に応じて事前に `setHandSignCallback()` を呼び出しておくこと。終了時は `closeHandsignWindow()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.openHandSignWindow();
```

#### void openSubWindow(int x, int y, int w, int h, float scale, string url)

独立した新規ウィンドウを開く。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `x` | `int` | 必須 | 数値。 |
| `y` | `int` | 必須 | 数値。 |
| `w` | `int` | 必須 | 数値。 |
| `h` | `int` | 必須 | 数値。 |
| `scale` | `float` | 必須 | 数値。 |
| `url` | `string` | 必須 | `file://` URI、`%APP%` / `%HOME%` プレースホルダ、または http URL。 |

##### 前提・後続 API

**独立した新規ウィンドウ**を開く。`url` には `file://` URI も許容。Windows はタイトルバー・ステータスバー付きの `SubWindowForm`、Android はオーバーレイ HTML ウィンドウ。`scale` は将来の ZoomFactor 用に予約され、現状は未使用。`openSubFrameWindow()` とは別の API なので混同しないこと。開いた後に `evalSubWindow()` を使う。終了時は `closeSubWindow()` を呼び出すこと

##### サンプル

```javascript
window.sticktv.openSubWindow(0, 0, 0, 0, 1.0, 'https://example.com/');
```

#### void closeSubWindow()

`openSubWindow()` で開いたウィンドウを閉じる。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

`openSubWindow()` で開いたウィンドウを閉じる。`openSubWindow()` の後に対となるように呼び出すこと

##### サンプル

```javascript
window.sticktv.closeSubWindow();
```

#### void evalSubWindow(string exp)

`openSubWindow()` で開いた独立サブウィンドウ内で JavaScript を評価（結果は取得できない）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `exp` | `string` | 必須 | 文字列。 |

##### 前提・後続 API

`openSubWindow()` で開いた**独立サブウィンドウ**内で JavaScript を評価（結果は取得できない）。`evalSubFrameWindow()` とは対象が異なるので混同しないこと。`openSubWindow()` 後に呼び出すこと

##### サンプル

```javascript
window.sticktv.evalSubWindow('');
```


---

### 更新・ウォッチドッグ・アプリ管理

#### void updateCheck()

Windows はダウンロード・解凍後に終了（確認ダイアログあり）。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

Windows はダウンロード・解凍後に終了（確認ダイアログあり）。Android はサーバーから最新版を確認してダウンロード。実行前に `getAppVersion()` 等で現在のバージョンを確認することがある

##### サンプル

```javascript
window.sticktv.updateCheck();
```

#### void initUpdate()

更新用フォルダ構成の初期化。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

更新用フォルダ構成の初期化。`updateCheck()` 等の前に呼び出すことがある

##### サンプル

```javascript
window.sticktv.initUpdate();
```

#### string getAppVersion()

バージョン文字列を返す。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

バージョン文字列を返す。Windows は `"<バージョン>,---"` 形式。更新確認や互換性判定の前に呼び出すことが多い

##### サンプル

```javascript
const result = await window.sticktv.getAppVersion();
console.log(result);
```

#### void startWatchDog(int minutes)

`minutes` 分ごとにアプリを再起動。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `minutes` | `int` | 必須 | 数値。 |

##### 備考

`0` 以下で停止。継続的な監視を行う場合は、`kickWatchDog()` との組み合わせで運用する

##### サンプル

```javascript
window.sticktv.startWatchDog(0);
```

#### void kickWatchDog()

ウォッチドッグカウントをリセット。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

ウォッチドッグカウントをリセット。`startWatchDog()` 実行中に定期的に呼び出すことで再起動を抑制する

##### サンプル

```javascript
window.sticktv.kickWatchDog();
```

#### void restartApplication()

アプリを再起動。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 前提・後続 API

アプリを再起動。データ保存などの後始末を終えてから呼び出すこと

##### サンプル

```javascript
window.sticktv.restartApplication();
```


---

### デモ版ライセンス

#### string requestDemoExtension(string message)

デモライセンスの延長をサーバーに要求。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `message` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |

##### 前提・後続 API

デモライセンスの延長をサーバーに要求。延長リクエスト前に `getAppVersion()` などでアプリ情報を確認することがある

##### サンプル

```javascript
const result = await window.sticktv.requestDemoExtension('');
console.log(result);
```


- `message` が空・未指定の場合は OS の入力ダイアログを表示し、氏名・メールアドレスを必ず含めた上で理由を入力します。Android 版は最大 5 分間ネイティブで待ち合わせます。
- 戻り値パターン:
  - 成功時: サーバーからの応答文字列
  - キャンセル時: `"error: cancelled"`
  - タイムアウト時（Android）: `"error: timeout"`
  - 空入力時（Android）: `"error: message is empty"`
  - 中断時（Android）: `"error: interrupted"`
  - Activity 非利用時（Android）: `"error: activity not available"`
  - ドメイン拒否時: `"error: invalid domain"`

---

### AI / OpenAI 互換 API（Ollama 等）

OpenAI 互換 API をネイティブ側から呼び出します。`baseUrl` を変更すれば任意の OpenAI 互換サーバーを利用できます。空文字の場合は製品既定のエンドポイント（Windows/Android とも `http://localhost:11434`）を使用します。タイムアウトは 120 秒。

> **注意**: `openaiModels` / `openaiChat` / `openaiChatImage` / `webSearch` の同期版は内部で `Task.Run(...).Result` で待ち合わせるため、Windows 版では UI スレッドを長時間ブロックします。長時間・確実な応答が必要な場合は `asyncOpenaiChat` / `asyncOpenaiChatImage` / `asyncWebSearch` を使用してください。

#### string openaiModels(string baseUrl, string apiKey)

`GET {baseUrl}/v1/models`。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `baseUrl` | `string` | 必須 | 文字列。 |
| `apiKey` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

```json
{"data":[{"id":"qwen3:8b","object":"model"}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `data` | `object[]` | モデル一覧 |
| `data[].id` | `string` | モデル ID |
| `data[].object` | `string` | `"model"` 固定 |
##### 前提・後続 API

`GET {baseUrl}/v1/models`。モデル一覧 JSON。`openaiChat()` / `openaiChatImage()` の前に利用可能モデルを確認するために使うことが多い

##### サンプル

```javascript
const result = await window.sticktv.openaiModels('', '');
console.log(result);
```

#### string openaiChat(string baseUrl, string apiKey, string model, string messagesJson, string searchApiKey)

`POST {baseUrl}/v1/chat/completions`。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `baseUrl` | `string` | 必須 | 文字列。 |
| `apiKey` | `string` | 必須 | 文字列。 |
| `model` | `string` | 必須 | 文字列。 |
| `messagesJson` | `string` | 必須 | 文字列。 |
| `searchApiKey` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### messagesJson の JSON スキーマ

OpenAI Chat Completions API の `messages` 配列と同形式です。

```json
[
  {"role":"system","content":"..."},
  {"role":"user","content":"こんにちは"},
  {"role":"assistant","content":"..."}
]
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `role` | `string` | 必須 | `"system"` / `"user"` / `"assistant"` / `"tool"` |
| `content` | `string` / `array` | 必須 | テキストメッセージ。vision モデル使用時は画像 URL オブジェクトを含む配列も可 |
| `content[].type` | `string` | 必須（配列要素） | `"text"` または `"image_url"` |
| `content[].text` | `string` | 必須（`type:text` 時） | テキスト内容 |
| `content[].image_url` | `object` | 必須（`type:image_url` 時） | 画像 URL オブジェクト |
| `content[].image_url.url` | `string` | 必須 | `data:image/png;base64,...` 形式のデータ URL |
| `tool_calls` | `object[]` | 任意 | モデルが要求した tool call 一覧（通常は応答側に含まれる） |

##### 戻り値 JSON スキーマ

成功時:

```json
{"choices":[{"message":{"role":"assistant","content":"..."}}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `choices` | `object[]` | 生成結果の配列 |
| `choices[].message` | `object` | 応答メッセージ |
| `choices[].message.role` | `string` | `"assistant"` |
| `choices[].message.content` | `string` | 応答テキスト |
| `choices[].message.tool_calls` | `object[]` | モデルが要求した tool call（通常は最終応答では省略される） |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

`POST {baseUrl}/v1/chat/completions`。tools 形式で `web_search` を登録し、モデルが必要と判断した場合のみ検索し最終回答を返す。使用する `model` は事前に `openaiModels()` で確認しておくことを推奨

##### サンプル

```javascript
const result = await window.sticktv.openaiChat('', '', '', '', '');
console.log(result);
```

#### void asyncOpenaiChat(string baseUrl, string apiKey, string model, string messagesJson, string callback, string searchApiKey)

非同期実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `baseUrl` | `string` | 必須 | 文字列。 |
| `apiKey` | `string` | 必須 | 文字列。 |
| `model` | `string` | 必須 | 文字列。 |
| `messagesJson` | `string` | 必須 | 文字列。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |
| `searchApiKey` | `string` | 必須 | 文字列。 |


##### messagesJson の JSON スキーマ

OpenAI Chat Completions API の `messages` 配列と同形式です。

```json
[
  {"role":"system","content":"..."},
  {"role":"user","content":"こんにちは"},
  {"role":"assistant","content":"..."}
]
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `role` | `string` | 必須 | `"system"` / `"user"` / `"assistant"` / `"tool"` |
| `content` | `string` / `array` | 必須 | テキストメッセージ。vision モデル使用時は画像 URL オブジェクトを含む配列も可 |
| `content[].type` | `string` | 必須（配列要素） | `"text"` または `"image_url"` |
| `content[].text` | `string` | 必須（`type:text` 時） | テキスト内容 |
| `content[].image_url` | `object` | 必須（`type:image_url` 時） | 画像 URL オブジェクト |
| `content[].image_url.url` | `string` | 必須 | `data:image/png;base64,...` 形式のデータ URL |
| `tool_calls` | `object[]` | 任意 | モデルが要求した tool call 一覧（通常は応答側に含まれる） |

##### コールバック JSON スキーマ

成功時:

```json
{"choices":[{"message":{"role":"assistant","content":"..."}}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `choices` | `object[]` | 生成結果の配列 |
| `choices[].message` | `object` | 応答メッセージ |
| `choices[].message.role` | `string` | `"assistant"` |
| `choices[].message.content` | `string` | 応答テキスト |
| `choices[].message.tool_calls` | `object[]` | モデルが要求した tool call（通常は最終応答では省略される） |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

非同期実行。完了時に `callback(responseJson)` を実行。`callback` は呼び出し前に定義しておくこと。長時間応答の前に `openaiModels()` でモデル確認を推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncOpenaiChat('', '', '', '', 'onResult', '');
```

#### string openaiChatImage(string baseUrl, string apiKey, string model, string searchApiKey, string imageDataUrl, string query)

画像付きメッセージで `web_search` tool を登録。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `baseUrl` | `string` | 必須 | 文字列。 |
| `apiKey` | `string` | 必須 | 文字列。 |
| `model` | `string` | 必須 | 文字列。 |
| `searchApiKey` | `string` | 必須 | 文字列。 |
| `imageDataUrl` | `string` | 必須 | 文字列。 |
| `query` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | 文字列。 |


##### 戻り値 JSON スキーマ

成功時:

```json
{"choices":[{"message":{"role":"assistant","content":"..."}}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `choices` | `object[]` | 生成結果の配列 |
| `choices[].message` | `object` | 応答メッセージ |
| `choices[].message.role` | `string` | `"assistant"` |
| `choices[].message.content` | `string` | 応答テキスト |
| `choices[].message.tool_calls` | `object[]` | モデルが要求した tool call（通常は最終応答では省略される） |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

画像付きメッセージで `web_search` tool を登録。モデルが必要と判断した場合のみ検索し、画像 + 検索結果で最終回答を返す。`imageDataUrl` は事前に `getDataBase64()` / `shrinkPhoto()` / `scanTwainImage()` などで生成しておくこと

##### サンプル

```javascript
const result = await window.sticktv.openaiChatImage('', '', '', '', '', '');
console.log(result);
```

#### void asyncOpenaiChatImage(string baseUrl, string apiKey, string model, string searchApiKey, string imageDataUrl, string query, string callback)

非同期実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `baseUrl` | `string` | 必須 | 文字列。 |
| `apiKey` | `string` | 必須 | 文字列。 |
| `model` | `string` | 必須 | 文字列。 |
| `searchApiKey` | `string` | 必須 | 文字列。 |
| `imageDataUrl` | `string` | 必須 | 文字列。 |
| `query` | `string` | 必須 | 文字列。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### コールバック JSON スキーマ

成功時:

```json
{"choices":[{"message":{"role":"assistant","content":"..."}}]}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `choices` | `object[]` | 生成結果の配列 |
| `choices[].message` | `object` | 応答メッセージ |
| `choices[].message.role` | `string` | `"assistant"` |
| `choices[].message.content` | `string` | 応答テキスト |
| `choices[].message.tool_calls` | `object[]` | モデルが要求した tool call（通常は最終応答では省略される） |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

非同期実行。完了時に `callback(responseJson)` を実行。`callback` は呼び出し前に定義しておくこと。`imageDataUrl` は事前に `getDataBase64()` / `shrinkPhoto()` / `scanTwainImage()` などで生成しておくこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncOpenaiChatImage('', '', '', '', '', '', 'onResult');
```


- `apiKey`: `Authorization: Bearer` ヘッダに設定される。Ollama ではダミー値（例: `"ollama"`）で構いません。
- `searchApiKey`: [Ollama Web Search API](https://ollama.com/settings/keys) の API キー。`openaiChat` 系は常に Web 検索を内蔵しており、空文字を渡すと検索を実行せず通常回答を返します。
- 画像の base64 は大きいため、ネイティブ側ログには先頭 200 文字のみ出力されます。
- モデル未ダウンロード時は先に `ollama pull` で取得してください。

### Web 検索

ネイティブ側から Web 検索 API を呼び出します。Windows/Android ともに **Ollama Web Search API**（`https://ollama.com/api/web_search`）を使用します。`apiKey` は [Ollama](https://ollama.com/settings/keys) で発行した API キー。検索結果は固定で最大 5 件です。

#### string webSearch(string apiKey, string query)

`[{"title":"...","url":"...","snippet":"...","displayUrl":"..."}, ...]`。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `string`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `apiKey` | `string` | 必須 | 文字列。 |
| `query` | `string` | 必須 | 文字列。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `string` | JSON 文字列。`JSON.parse()` して利用。 |


##### 戻り値 JSON スキーマ

成功時:

```json
[{"title":"...","url":"...","snippet":"...","displayUrl":"..."}]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `title` | `string` | ページタイトル |
| `url` | `string` | 実際の URL |
| `snippet` | `string` | 検索結果のスニペット |
| `displayUrl` | `string` | 表示用 URL |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 備考

失敗時は `{"error":"..."}`。検索結果は最大 5 件。取得した URL を `getUrl()` / `getUrlBase64()` で読み込むことも多い

##### サンプル

```javascript
const result = await window.sticktv.webSearch('', '');
console.log(result);
```


##### 備考

- `callback`: 結果を受け取る JavaScript 関数名。レスポンス文字列は JS 文字列リテラルとして安全に埋め込めるようエスケープされて渡されます。
- **注意**: API キーはクライアント側に露出するため、社内限定・PoC・一時的な用途向けです。公開キオスク等では自社プロキシ方式への移行を推奨します。
#### void asyncWebSearch(string apiKey, string query, string callback)

完了時に `callback(responseJson)` を実行。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `apiKey` | `string` | 必須 | 文字列。 |
| `query` | `string` | 必須 | 文字列。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### コールバック JSON スキーマ

成功時:

```json
[{"title":"...","url":"...","snippet":"...","displayUrl":"..."}]
```

| フィールド | 型 | 説明 |
|---|---|---|
| `title` | `string` | ページタイトル |
| `url` | `string` | 実際の URL |
| `snippet` | `string` | 検索結果のスニペット |
| `displayUrl` | `string` | 表示用 URL |

失敗時:

```json
{"error":"..."}
```

| フィールド | 型 | 説明 |
|---|---|---|
| `error` | `string` | エラーメッセージ |
##### 前提・後続 API

完了時に `callback(responseJson)` を実行。`callback` は呼び出し前に定義しておくこと。結果を受け取った後に `getUrl()` / `getUrlBase64()` でページ内容を取得することが多い

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.asyncWebSearch('', '', 'onResult');
```


### MQTT クライアント

MQTT ブローカーとの pub/sub 通信を行います。Windows 版は MQTTnet、Android 版は HiveMQ MQTT Client を使用しています。

#### bool mqttConnect(string brokerUrl, string clientId, string optionsJson)

`brokerUrl` は `mqtt://` / `mqtts://` / `tcp://` / `ssl://` をサポート。 **Windows 版は `Task<T>` のため JS 側で `await` が必要**。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `brokerUrl` | `string` | 必須 | 文字列。 |
| `clientId` | `string` | 必須 | 文字列。 |
| `optionsJson` | `string` | 必須 | JSON 文字列で指定するオプション。詳細は同カード内の「optionsJson の JSON スキーマ」を参照。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### optionsJson の JSON スキーマ

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `username` | `string` | 任意 | ユーザー名 |
| `password` | `string` | 任意 | パスワード |
| `cleanSession` | `boolean` | 任意 | クリーンセッション開始 |
| `keepAlive` | `number` | 任意 | keepAlive 間隔（秒） |
| `sessionExpiry` | `number` | 任意 | 接続断開後のセッション有効期間（秒）。Windows 版のみ有効 |
| `tls` | `object` | 任意 | TLS 設定 |
| `tls.enabled` | `boolean` | 任意 | TLS を有効化。`mqtts://` / `ssl://` では暗黙的に有効 |
| `tls.allowUntrusted` | `boolean` | 任意 | 信頼できない証明書を許可 |
| `tls.ignoreChainErrors` | `boolean` | 任意 | 証明書チェーンエラーを無視 |
| `tls.ignoreRevocationErrors` | `boolean` | 任意 | 失効確認エラーを無視 |
| `will` | `object` | 任意 | ラストウィル設定 |
| `will.topic` | `string` | 必須 | ウィルメッセージのトピック |
| `will.payload` | `string` | 必須 | ウィルメッセージのペイロード |
| `will.qos` | `number` | 任意 | QoS レベル |
| `will.retain` | `boolean` | 任意 | Retain フラグ |

- Windows 版の TLS オプションでは `caFile` / `clientCertFile` / `clientKeyFile` は現在未対応。 |
##### 前提・後続 API

`brokerUrl` は `mqtt://` / `mqtts://` / `tcp://` / `ssl://` をサポート。`clientId` が空の場合は自動生成。**Windows 版は `Task<bool>` なので JS 側では `await` が必要**。`mqttPublish()` / `mqttSubscribe()` / `mqttIsConnected()` の前に必ず呼び出すこと。必要に応じて事前に `mqttSetEventCallback()` を設定しておくこと

##### サンプル

```javascript
const ok = await window.sticktv.mqttConnect('', '', JSON.stringify({}));
if (!ok) console.error('mqttConnect 失敗');
```

#### bool mqttDisconnect()

Windows 版は `Task<bool>` なので JS 側では `await` が必要。 **Windows 版は `Task<T>` のため JS 側で `await` が必要**。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

**Windows 版は `Task<bool>` なので JS 側では `await` が必要**。`mqttConnect()` の後に対となるように呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.mqttDisconnect();
if (!ok) console.error('mqttDisconnect 失敗');
```

#### bool mqttSubscribe(string topic, int qos, string callback)

`callback(json)` で受信メッセージを通知。 **Windows 版は `Task<T>` のため JS 側で `await` が必要**。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `topic` | `string` | 必須 | MQTT トピック名。 |
| `qos` | `int` | 必須 | QoS レベル（`0` / `1` / `2`）。 |
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |


##### コールバック JSON スキーマ

```json
{ "topic": "sticktv/test", "payload": "{\"hello\":\"sticktv\"}", "qos": 0, "retain": false }
```

| フィールド | 型 | 説明 |
|---|---|---|
| `topic` | `string` | 受信トピック |
| `payload` | `string` | 生のペイロード文字列。JSON として解析したい場合は JS 側で `JSON.parse()` する |
| `qos` | `number` | 受信 QoS レベル |
| `retain` | `boolean` | Retain フラグ |
##### 前提・後続 API

`callback(json)` で受信メッセージを通知。**Windows 版は `Task<bool>` なので JS 側では `await` が必要**。`callback` は呼び出し前に定義しておくこと。`mqttConnect()` 成功後に呼び出すこと

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

const ok = await window.sticktv.mqttSubscribe('sticktv/test', 0, 'onResult');
if (!ok) console.error('mqttSubscribe 失敗');
```

#### bool mqttUnsubscribe(string topic)

Windows 版は `Task<bool>` なので JS 側では `await` が必要。 **Windows 版は `Task<T>` のため JS 側で `await` が必要**。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `topic` | `string` | 必須 | MQTT トピック名。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

**Windows 版は `Task<bool>` なので JS 側では `await` が必要**。`mqttSubscribe()` の後に対となるように呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.mqttUnsubscribe('sticktv/test');
if (!ok) console.error('mqttUnsubscribe 失敗');
```

#### bool mqttPublish(string topic, string payloadJson, int qos, bool retain)

`payloadJson` は JSON 文字列をそのまま送信。 **Windows 版は `Task<T>` のため JS 側で `await` が必要**。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `topic` | `string` | 必須 | MQTT トピック名。 |
| `payloadJson` | `string` | 必須 | 送信する JSON 文字列。 |
| `qos` | `int` | 必須 | QoS レベル（`0` / `1` / `2`）。 |
| `retain` | `bool` | 必須 | 真偽値。 |

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

`payloadJson` は JSON 文字列をそのまま送信。JSON として解析できない場合は生文字列を送信。**Windows 版は `Task<bool>` なので JS 側では `await` が必要**。`mqttConnect()` 成功後に呼び出すこと

##### サンプル

```javascript
const ok = await window.sticktv.mqttPublish('sticktv/test', JSON.stringify({ hello: 'sticktv' }), 0, true);
if (!ok) console.error('mqttPublish 失敗');
```

#### bool mqttIsConnected()

接続状態を取得。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `bool`

##### 戻り値

| 型 | 内容 |
|---|---|
| `bool` | 成功時 `true`、失敗・ドメイン拒否時 `false`。 |

##### 前提・後続 API

接続状態を取得。`mqttConnect()` 後に `mqttPublish()` / `mqttSubscribe()` を呼び出す前に確認することが多い

##### サンプル

```javascript
const ok = await window.sticktv.mqttIsConnected();
if (!ok) console.error('mqttIsConnected 失敗');
```

#### void mqttSetEventCallback(string callback)

接続/切断/エラー時に `callback(json)` を通知。

- **対応プラットフォーム**: Windows ○ / Android ○
- **戻り値**: `void`

##### 引数

| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| `callback` | `string` | 必須 | JavaScript 側で事前に定義したコールバック関数名を文字列で指定。 |


##### コールバック JSON スキーマ

```json
{ "event": "connected|disconnected|error", "message": "..." }
```

| フィールド | 型 | 説明 |
|---|---|---|
| `event` | `string` | `"connected"` / `"disconnected"` / `"error"` |
| `message` | `string` | イベント詳細メッセージ |
##### 前提・後続 API

接続/切断/エラー時に `callback(json)` を通知。Windows は `void`、Android は `bool` だが両方とも呼び出し可能。`callback` は呼び出し前に定義しておくこと。`mqttConnect()` 前または直後に設定しておくことを推奨

##### サンプル

```javascript
function onResult(json) {
  const data = JSON.parse(json);
  console.log(data);
}

window.sticktv.mqttSetEventCallback('onResult');
```