Xiaoi

🚀 小爱音箱语音通知工具

このツールは CLI / TUI / MCP / Webhook を通じて、小爱音箱に音声通知を送信することができます。

🚀 クイックスタート

このツールを使用することで、様々な方法を通じて小爱音箱に音声通知を送信できます。以下に、主な機能と使い方を紹介します。

✨ 主な機能

• TUI 交互界面：アカウントの設定、通知の送信、Webhook/PM2 の管理ができます。
• CLI 命令：スクリプトや自動化シーンに適しています。
• MCP Server：Codex/Cursor/VS Code などの AI プログラミングアシスタントから呼び出すことができます。
• Webhook 服务：HTTP インターフェースを提供し、サードパーティシステムとの統合が容易です。
• 多音箱路由：スピーカーリストの管理、デフォルトスピーカーの設定、リクエストの did による一時的な上書きがサポートされています。
• PM2 常驻：Webhook をワンクリックでバックグラウンドで実行できます（ターミナルを開いておく必要がありません）。

📦 インストール

グローバルインストール（推奨）

# npm
npm i -g xiaoii

# または pnpm
pnpm add -g xiaoii

インストール後、どのディレクトリでも xiaoi と xiaoi-mcp コマンドを使用できます。

ソースコードからインストール

git clone https://github.com/xvhuan/xiaoi.git
cd xiaoi

# npm
npm i
npm link

# または pnpm
pnpm install
pnpm link --global

📚 ドキュメント

自動作成（インストール/初回実行時）

インストールが完了するか、初めて xiaoi を実行すると、自動的に以下が作成されます。

• ディレクトリ：~/.xiaoi/（Windows の場合は %USERPROFILE%\.xiaoi\）
• 設定ファイル：~/.xiaoi/config.json（空のテンプレート）

手動設定

~/.xiaoi/config.json を編集します。

{
    "speaker": {
        "userId": "あなたの小米ID（数字、携帯番号ではありません）",
        "password": "あなたのパスワード（推奨しません）",
        "passToken": "あなたのpassToken（推奨）",
        "did": "米家アプリでのスピーカー名",
        "defaultDid": "デフォルトスピーカーの did（オプション）",
        "speakers": [
            {
                "did": "スピーカーの did",
                "name": "リビングの小爱",
                "model": "lx04",
                "enabled": true
            }
        ],
        "ttsMode": "auto",
        "verboseLog": false,
        "ttsFallbackCommand": [5, 1],
        "ttsFallbackCommands": {
            "oh2p": [7, 3],
            "oh2": [5, 3],
            "lx06": [5, 1],
            "s12": [5, 1],
            "l15a": [7, 3],
            "lx5a": [5, 1],
            "lx05": [5, 1],
            "x10a": [7, 3],
            "l17a": [7, 3],
            "l06a": [5, 1],
            "lx01": [5, 1],
            "l05b": [5, 3],
            "l05c": [5, 3],
            "l09a": [3, 1],
            "lx04": [5, 1],
            "asx4b": [5, 3],
            "x6a": [7, 3],
            "x08e": [7, 3],
            "x8f": [7, 3]
        }
    },
    "webhook": {
        "port": 51666,
        "host": "localhost",
        "token": "",
        "logFile": "log/webhook.log"
    },
    "mcp": {
        "logFile": "log/mcp_server.log"
    }
}

設定ファイルの検索優先順位：

1. ~/.xiaoi/config.json
2. （フォールバック）インストールディレクトリ/プロジェクトディレクトリ内の config.json

主なフィールドの説明：

Webhook のデフォルトスピーカーの優先順位：

1. speaker.defaultDid
2. XIAOI_DEFAULT_DID（環境変数）
3. speaker.did（互換性のためのフィールド）

リクエストボディで明示的に did を指定する場合、did は speaker.speakers に含まれ、enabled=true である必要があります。そうでない場合は 400 が返されます。

ヒント：TUI の「アカウント設定」で TTS モードを切り替え、デフォルト/モデルの ttscmd を変更、詳細ログをオン/オフできます。「接続テスト」では、一時的な ttscmd と一時的なモードを手動で入力してデバッグできます。

推奨：passToken を使用してログインしてください。passToken の取得方法は migpt-next/issues/4 を参照してください。

💻 使用例

TUI 交互界面

xiaoi

CLI 命令

# 音声通知の送信
xiaoi tts "コードのコンパイルが完了しました"
xiaoi tts デプロイが完了しました。確認してください

# 音量の設定
xiaoi volume 30

# MiOT コマンドの送信（オプションで did を指定）
xiaoi command 3 1 "[]"
xiaoi command 3 1 '[{"piid":1,"value":true}]' --did リビングの小爱

# MiOT 属性の読み取り（オプションで did を指定）
xiaoi getprop 3 1 --did リビングの小爱

# 接続状態の確認
xiaoi status

# ヘルプ
xiaoi help

MiOT cmd の簡単な例（xiaomi.wifispeaker.oh2p）

• 米家の仕様書（あなたのスピーカーの例）：https://home.miot-spec.com/spec/xiaomi.wifispeaker.oh2p
• このモデルの一般的な TTS ttscmd：[7,3]

# 1) 最も簡単な方法：直接 TTS を送信（推奨）
xiaoi tts "主人、これは OH2P のテストです" --did あなたのデバイスの did

# 2) MiOT cmd を使用して TTS を送信（oh2p の一般的な [7,3]）
xiaoi command 7 3 "[\"主人，这是一条 OH2P cmd 测试\"]" --did あなたのデバイスの did

# 3) playing-state を読み取る（SIID=3, PIID=1）
xiaoi getprop 3 1 --did あなたのデバイスの did
# 返り値の一般的な意味：1=再生中、0=停止、2=一時停止

cmd（siid/aiid/params）を構築する簡単な方法：

1. 対応するデバイスの仕様書ページを開きます（上記の oh2p のリンクなど）。
2. 目的の機能に対応する Service / Action を見つけ、siid と aiid を記録します。
3. その Action のパラメータ定義に従って params を準備します：パラメータがない場合は []、パラメータがある場合はドキュメントの順序に従って JSON 配列を組み立てます。
4. 実行：xiaoi command <siid> <aiid> '<paramsJson>' [--did <デバイスの did>]。

注意：異なるアクションの params の構造は異なります。必ず仕様書のアクションパラメータ定義に従ってください。

MCP Server（AI プログラミングアシスタントとの統合）

まず、xiaoi をグローバルにインストールし、アカウント設定を完了する必要があります。

VS Code / Cursor（JSON）

プロジェクト内に .vscode/mcp.json を作成します。

{
  "servers": {
    "xiaoi-voice-notify": {
      "type": "stdio",
      "command": "xiaoi-mcp"
    }
  }
}

Codex CLI（TOML）

[mcp_servers.xiaoi-voice-notify]
command = "xiaoi-mcp"

ツールのリスト：

これら 5 つの MCP ツールはすべて、オプションパラメータ did をサポートしています。指定しない場合はデフォルトのスピーカーが使用され、指定した場合は指定されたスピーカーが使用されます。

Webhook サービス（HTTP インターフェース）

TUI で Webhook を起動することも、PM2 を使用して常駐させることもできます（次のセクションを参照）。

webhook.token を設定した場合（または常駐 Webhook で自動生成されたトークンを使用する場合）、リクエストに次のヘッダーを含めてください。

• Authorization: Bearer <token>
• または X-Xiaoi-Token: <token>

リクエストボディで did を指定することで、今回のターゲットスピーカーを指定することもできます。指定しない場合は、デフォルトの優先順位に従って自動的にルーティングされます。

# 音声通知の送信（オプションで did を指定してターゲットスピーカーを指定）
curl -X POST http://localhost:51666/webhook/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"text":"こんにちは、世界","did":"リビングの小爱"}'

# オーディオの再生（オプションで did を指定）
curl -X POST http://localhost:51666/webhook/audio \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"url":"https://example.com/audio.mp3","did":"寝室の小爱"}'

# 音量の設定（オプションで did を指定）
curl -X POST http://localhost:51666/webhook/volume \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"volume":50,"did":"リビングの小爱"}'

# MiOT コマンドの送信（オプションで did を指定）
curl -X POST http://localhost:51666/webhook/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"siid":3,"aiid":1,"params":[],"did":"リビングの小爱"}'

Webhook の常駐（PM2 でワンクリック起動）

Webhook をサーバー/コンピューターで長期間バックグラウンドで実行したい場合は（ターミナルを開いておく必要がありません）、組み込みの PM2 管理コマンドを使用します。

# ワンクリックで常駐起動（バックグラウンドで実行）
xiaoi pm2 start

# ワンクリックでデプロイ（start + save）
xiaoi pm2 deploy

# 状態の確認
xiaoi pm2 status

# pm2 プロセスのログを表示（stdout/stderr）
xiaoi pm2 logs 200

# Webhook のログファイルを表示（~/.xiaoi/log/webhook.log など）
xiaoi pm2 webhook-log 200

# 公開アクセスのオン/オフ（webhook.host を変更）
xiaoi pm2 public on
xiaoi pm2 public off

# 停止/削除
xiaoi pm2 stop
xiaoi pm2 delete

# プロセスリストの保存（pm2 startup と組み合わせると、起動時に自動起動できます）
xiaoi pm2 save

# 起動時の自動起動コマンドの生成（通常は管理者/Root 権限が必要です）
xiaoi pm2 startup

Webhook を外部ネットワークに公開する場合は、必ず webhook.token を設定するか、ファイアウォール/リバースプロキシと組み合わせて認証を行い、任意の呼び出しを防いでください。

Docker デプロイ（コンテナ化された Webhook）

xiaoi Webhook を Docker コンテナにパッケージ化して実行することができます。サーバー/NAS/クラウドホストに適しています。基本的なシーンでは、設定ファイルを手動で編集する必要はありません。環境変数を設定するだけで起動できます（複数のスピーカーのシーンについては、以下の「複数のスピーカーの設定」を参照）。

クイックスタート（直接イメージを取得し、clone する必要はありません）

# イメージの取得
docker pull iusy/xiaoi:latest

# 一行で起動
docker run -d \
  --name xiaoi-webhook \
  --restart unless-stopped \
  -p 51666:51666 \
  -e XIAOI_USER_ID=あなたの小米ID \
  -e XIAOI_PASS_TOKEN=あなたのpassToken \
  -e XIAOI_DID=あなたのスピーカー名 \
  -e XIAOI_DEFAULT_DID=デフォルトスピーカーの did \
  -e XIAOI_TOKEN=あなたのWebhook認証トークン \
  iusy/xiaoi:latest

完了です！🎉 コードを clone する必要も、設定ファイルを編集する必要もありません。

または Docker Compose を使用する

# 1. docker-compose.yml と .env テンプレートをダウンロード
curl -O https://raw.githubusercontent.com/xvhuan/xiaoi/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/xvhuan/xiaoi/main/.env.example

# 2. .env を編集して、あなたの情報を入力
#    XIAOI_USER_ID、XIAOI_PASS_TOKEN、XIAOI_DID（オプションで XIAOI_DEFAULT_DID）

# 3. ワンクリックで起動
docker-compose up -d

.env ファイルには、少なくとも 3 つの項目を入力することをお勧めします（オプションでデフォルトのスピーカーを追加）。

XIAOI_USER_ID=あなたの小米ID（数字）
XIAOI_PASS_TOKEN=あなたのpassToken
XIAOI_DID=あなたのスピーカー名
XIAOI_DEFAULT_DID=デフォルトスピーカーの did
XIAOI_TOKEN=あなたのWebhook認証トークン

passToken の取得方法：migpt-next/issues/4

複数のスピーカーの設定（2 つの方法）

複数のスピーカーを持っている場合は、ターゲットデバイスをすべて speaker.speakers に記述し、speaker.defaultDid を設定することをお勧めします。

方法 1：コンテナ内で xiaoi を使用して対話的に設定する（手動での運用に適しています）

# docker run でデプロイした場合
docker exec -it xiaoi-webhook node /app/bin/xiaoi.js

# docker compose でデプロイした場合
docker compose exec xiaoi-webhook node /app/bin/xiaoi.js

その後、TUI で アカウント設定 -> スピーカーリスト管理 に移動し、「スピーカーの追加/デフォルトスピーカーの設定」を完了します。

方法 2：設定ファイルを直接編集する（バッチ/自動化に適しています）

コンテナ内の設定ファイルのパス：/root/.xiaoi/config.json（永続的なボリュームをマウントしていることが前提）。

{
  "speaker": {
    "defaultDid": "リビングのスピーカーの did",
    "speakers": [
      { "did": "リビングのスピーカーの did", "name": "リビング", "model": "oh2p", "enabled": true },
      { "did": "寝室のスピーカーの did", "name": "寝室", "model": "lx04", "enabled": true }
    ]
  }
}

変更後、コンテナを再起動すると設定が反映されます。

docker restart xiaoi-webhook
# または
docker compose restart xiaoi-webhook

呼び出し規則：

1. リクエストに did を指定しない場合：デフォルトのスピーカーが使用されます（defaultDid > XIAOI_DEFAULT_DID > speaker.did）
2. リクエストに did を指定した場合：指定されたスピーカーが使用されます
3. did は speaker.speakers に含まれ、enabled=true である必要があります

純粋な Docker コマンド（docker-compose を使用しない場合）

# イメージのビルド
docker build -t xiaoi-webhook .

# 実行（-e で環境変数を直接渡す）
docker run -d \
  --name xiaoi-webhook \
  --restart unless-stopped \
  -p 51666:51666 \
  -e XIAOI_USER_ID=あなたの小米ID \
  -e XIAOI_PASS_TOKEN=あなたのpassToken \
  -e XIAOI_DID=あなたのスピーカー名 \
  -e XIAOI_DEFAULT_DID=デフォルトスピーカーの did \
  xiaoi-webhook

環境変数の一覧

サービスの検証

# コンテナのログを表示（トークンと起動状態を確認）
docker-compose logs

# 状態の確認
curl http://localhost:51666/

# 音声通知の送信
curl -X POST http://localhost:51666/webhook/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ログから取得したトークン>" \
  -d '{"text":"Docker デプロイに成功しました！"}'

よく使うコマンド

# ログの表示
docker-compose logs -f

# 再起動
docker-compose restart

# 停止
docker-compose down

# 更新（最新のコードを取得した後）
git pull
docker-compose up -d --build

🔧 技術詳細

プロジェクト構造

xiaoi/
├── bin/
│   └── xiaoi.js              # CLI + TUI のエントリーポイント
├── lib/
│   ├── config.js             # ユーザーディレクトリの設定管理（自動的に ~/.xiaoi/config.json を生成）
│   ├── speaker.js            # コアモジュール（スピーカー API への直接接続）
│   ├── tui.js                # TUI 交互界面
│   ├── webhook_server.js     # 常駐 Webhook サービスのエントリーポイント（PM2 と組み合わせて使用できます）
│   └── pm2.js                # PM2 のワンクリック管理のラッパー
├── mcp_server.js             # MCP Server
├── config.example.json       # 設定テンプレート
├── Dockerfile                # Docker イメージのビルド
├── docker-compose.yml        # Docker Compose のオーケストレーション
├── docker-entrypoint.sh      # コンテナの起動エントリースクリプト
├── .env.example              # Docker の環境変数テンプレート
└── README.md

よくある質問

ログインに失敗した場合はどうすればいいですか？

1. userId が小米 ID（数字）であることを確認してください。携帯番号やメールアドレスではありません。
2. パスワードでのログインの代わりに、passToken を使用することをお勧めします。
3. passToken の取得方法は migpt-next/issues/4 を参照してください。

デバイスが見つからない場合はどうすればいいですか？

• did が米家アプリでのスピーカー名と完全に一致していることを確認してください。

謝辞

このプロジェクトは @mi-gpt/next をベースに構築されています。 https://github.com/idootop/migpt-next

📄 ライセンス

MIT ライセンスです。詳細は LICENSE を参照してください。