アクション

アクションは、オーバーレイに表示される HTML、CSS、JavaScript のひとまとまりです。それぞれが独立して動き、ネットワークにもパスワードにもアクセスできません。外から必要なものは Vovó に頼みます。

はじめる

「新しいアクション」で、空のアクションか、例から作ったアクションを作ります。例には、アラートとチャット、再生中の曲、カウントダウン、目標、抽選、デスカウンターなどがあります。例はあなたのコピーになるので、自由に変えられます。

三つの段階

HTML だけ：イベントが起きたときに表示される <template> で、イベントのフィールドは波かっこで書きます。

<template data-on="follow" data-seconds="5">
    <div class="alert">{user} さんがフォローしました！</div>
</template>

少しの JavaScript：vovo.on("raid", (e) => { ... }) と vovo.show("name", e)。そして残りは API 全体で。

• API リファレンス
• アクションの動き方

トリガー

アクションが受け取るのは、エディターのトリガー一覧にあるイベントだけです。パッドのボタンは button トリガーです。

条件

トリガーの横のスライダーアイコンで条件が開きます。トリガーは、すべての条件を満たしたときだけ発火します。50 人以上のレイド、!参加 で始まるメッセージ、特定の特典などです。

タイマーとホットキー

タイマートリガーは一定間隔で発火します。条件 every で何秒ごとかを指定します（なければ毎分）。ホットキートリガーはキーの組み合わせ（条件 keys）で、ゲームが前面にあっても発火します。

コントロール

エディターのコントロールカードで、アクションは実行中にパッドから変えられるものを宣言します。オン・オフ、選択肢からの選択、カウンター（目標付きも可）、テキストです。それぞれはダイアログに表示されるキーで vovo.state に保存され、変更は control イベントとして届きます。トリガーは要りません。アラートとチャット、フォロワー目標、デスカウンターの例でやり方がわかります。

vovo.on("control", () =>
{
    document.getElementById("chat").hidden = !vovo.state.chat;
});

カスタマイズ

アクションは、使う人がコードを開かずに変えられるようにできます。色、文字の大きさ、フォント、画面のどちら側か、自分の画像や音などです。パネル名の横、またはアクション一覧のその行にあるパレットでカスタマイズが開きます。設定ごとに一行あり、今の値、異なる場合は既定値、既定値に戻す方法が表示されます。変更はアクションを再起動せずに、そのアクションを表示しているシーンにすぐ反映され、どの変更も操作ログで元に戻せるバージョンになります。選べるのはこのコンピューターでだけで、スマホや別の Vovó からは見えません。アクションのパッケージには既定値だけが入り、あなたの選択は入りません。アクションに置き換わるパッケージは、まだ入る余地のある選択を引き継ぎます。

アクションを書く人は、エディターのカスタマイズカードか、action.json の settings でこれを宣言します。それぞれに種類（色、最小から最大までの数、オン・オフ、選択肢、テキスト、画像、音や動画、フォント）、名前、キー、既定値があります。アクションは vovo.settings で読み、変わると settings イベントを受け取ります。CSS では var(--vovo-キー)（32px のように単位付きの数）として、オン・オフや選択肢はセレクター用のページの属性として読めます。

.chat
{
    color: var(--vovo-color);
    font-size: var(--vovo-size);
    font-family: var(--vovo-font), sans-serif;
}
html[data-vovo-side="Right"] .chat
{
    right: 40px;
}

設定はカメラにもできます。アクションを使う人が「カスタマイズ」で自分のコンピューターのカメラを選び、アクションは自分が置いた場所にそれを表示します（vovo.camera.place、camera.show 権限が必要）。アクションにはカメラが付いておらず、どれが選ばれたかを知ることも、映像を見ることもありません。vovo.settings は、選ばれているかどうかを true か false で伝えるだけです。「カメラ」の例は、枠に入ったカメラです。

パネル

ボタンに収まらないもの（抽選の参加者の名前、数字付きの目標、二度確認したい操作）は、アクションのパネルに入れます。マニフェストの panel に書き、サイドバーのパネル（いずれかのアクションにパネルがある間、ウィンドウの右端にアイコンが出ます）に表示されます。パネルは Vovó が描く部品のリストです。heading と note、キーで指定する control、button（confirm を付けるとまず「本当に？」と聞きます）、最大 4 項目の form、vovo.state から読む list（その key と、中の path）で、各行には最大 3 つのボタンを付けられます。

提供するものが多いアクションは、二通りに分けられます。{ "kind": "panel", "label": "抽選", "icon": "gift" } は別のパネルを始めます。パネルの中に独自の項目ができ、名前とアイコン（Vovó のアイコン名か絵文字。なければアクションの最初のパッドボタンのアイコン）を持ちます。次のパネルまでの部品はそのパネルのもので、最初のパネルより前の部品はすべてのパネルの上部に表示されます。パネルの中では tab がセクションを始めます（最大 12 個）。次のタブまでの部品はそのセクションを選んでいる間だけ表示され、最初のタブより前の部品はすべてのセクションに表示されます。こうして抽選は、長い一枚のページではなく、抽選、参加者、当選者のセクションを持つひとつのパネルになります。{ "kind": "panel" } をひとつも宣言しないアクションには、アクション名のパネルがひとつあります。

パネルのヘッダーは手前のパネルの名前を表示し、押すと全パネルの一覧が出ます。それぞれ、開いているシーンが表示しているか、どのアクションのものかがわかり、8 個を超えると検索が付きます。セクションはヘッダーの下にタブとして並び、入りきらないものは「その他」にまとまります。見出しはグループを始めます。その後の部品はひとつのカードを共有し、続くボタンは一行を共有し、リストは件数付きの独立したカードになり、メモはカードの間に置かれます。1 項目のフォームはパネル内で直接入力し、Enter で送信します。テキストのコントロールも同じです。項目が多いフォームは小さなウィンドウを開きます。目標（max）付きのカウンターは進み具合を表示します。

リストは何千行にもなれます。8 行を超えるリストには専用の検索があり、リストをスクロールしても見えたままです。セクションの最後の部品ならリスト全体が表示され、後ろに部品があると最初の 8 行と全行への入口が表示されます。長いリストは最後に置くか、専用のセクションに入れてください。

そこで行った操作は、トリガーなしで panel イベントとして届きます。name、フォームの values、行の item と index が含まれます。名前はどのパネルに表示されていてもアクションのものです。アクションがパネルの操作を受け取れるのは、開いているシーン（OBS かプレビューウィンドウ）がそのアクションを表示している間だけです。ひとつもなければパネルがそう伝え、ボタンは薄く表示されて待ち、「プレビューを開く」でシーンのプレビューが開きます。コントロールとリストは Vovó が保存しているので、そのまま表示されます。使えるのは配信を操作する人だけで、ここか、パネルを許可したデバイスからです。パニック中はアクションに何も届きません。

チャットに書き込む

chat.send 権限があれば、vovo.chat.send("...") で配信のチャットにあなたとして書き込めます。Vovó はペース（30 秒で 20 行）を守り、アクションを表示している二つのページが同じことを頼んでも一度だけ書き込みます。ボタンを二回押せば二行です。チャットのリマインダーの例でやり方がわかります。{ as: "persona" } を付けると、代わりにペルソナ自身の Twitch アカウント（連携の Twitch の下）から書き込みます。ペルソナの回答ではない発言、たとえば誰かがペルソナに言わせるために打った一行です。そのアカウントが接続されていない間は何も書き込まず、代わりにあなたとして書くこともありません。

Vovó は、呼び出したときにアクションが処理していたイベントで、どのページからの呼び出しかを見分けます。await のあとやタイマーの中など、あとから行う呼び出しは、{ event: e } でどのイベントへの応答かを示します。e はリスナーが受け取ったものです：vovo.chat.send("ようこそ！", { event: e })。vovo.emit、vovo.pad.play、vovo.webhook.send、vovo.draw、vovo.media.play、OBS の呼び出しも同じです。これがないと二つのページが同じ行を二回書き込み、モデレーターのリンクはベルで待つことになります。

マイク、画面、あなたの動き

アクションは、マイクの音量（audio.level）、画面の色（screen.color）、ゲームでの動き（input.move）を追えます。動きとは、カメラがどれだけ回ったか、どちらへ歩いているか、ジャンプしたかで、マウス、W・A・S・D や矢印キー、コントローラーから読み取ります。シーンをカメラに合わせて揺らせます。「画面のグロー」と「カメラの揺れ」の例でやり方がわかります。Vovó がそれぞれを読むのは、開いているオーバーレイがそれを待つアクションを表示している間だけで、その間はステータスバーの中央にアイコンが表示され、ツールチップにアクション名が出ます。キーボードは移動キーだけを方向として読み、どのキーかは記録しません。Vovó のウィンドウが前面にある間は読みません。そこで入力した文字でシーンが揺れてしまうからです。ただしマウスとコントローラーは、「Vovó が前面にあるときは動きを止める」（設定 › 全般）がオンでない限り、そのときも動かします。音はコンピューターから出ません。出るのは音量だけです。

クリップと動画

media.play 権限があれば、vovo.media.play(リンク) で Twitch のクリップ、Twitch の動画、YouTube の動画を公式プレーヤーで、vovo.media.place(要素) で置いた場所に音付きで表示します。操作する人だけが起動するアクションならすぐ再生されます。チャットの誰かが起動したかもしれない他のアクションは、あなた（または承認を許可したデバイス）が通すまでベルで待ちます。プレーヤーはクリップがいつ終わるかわからないので、{ seconds: 60 } を渡すか vovo.media.stop() を呼んでください。テレビでクリップの例は、モデレーターからの !clip とリンクを受け付けます。

モデレーターは、あなたがチャットを任せている人たちです。連携の Twitch にある「モデレーターのリンクはすぐ再生」をオンにすると、モデレーター（またはあなた）が貼ったリンクは、そのメッセージをきっかけにアクションが表示するとき、待たずに配信に乗ります。オンにするまではオフです。それ以外の人のリンクは引き続き待ちます。

音声通話

call 権限があれば、アクションは配信中にあなたを AI モデルと電話でつなげます。あなたがマイクに話し、モデルが声で答え、配信には両方が聞こえます。vovo.call.start({ instructions, voice }) はあなたの OpenAI キー（連携 › AI）で通話を開きます。instructions はモデルが誰でどう話すかです。通話は無音で開くので、アクションは先に電話の呼び出し音を鳴らせます。vovo.call.answer() はマイクを開いてモデルに先に話させ、vovo.call.tell() は通話中に何かを伝え、vovo.call.end() は通話を切ります。call.started、call.answered、call.text（話した内容の文字起こし）、call.ended が経過を知らせます。

モデルの言葉は、誰も先に読まないまま話したそのときに聞こえるので、通話はあなたが手で行ったことからしか始まりません。パッドのボタン、ホットキー、コントロール、アクションのパネルです。チャット、特典、Webhook からは始まりません。OpenAI は開いた瞬間から秒単位で課金するので、通話には上限があります（最大 5 分）。通話中はステータスバーに赤い電話が表示されます。それかパニックを押すとすぐに切れます。ヘッドホンを使ってください。そうしないと、モデルがスピーカーから自分の声を聞いてしまいます。

Webhook

webhook 権限があれば、vovo.webhook.send("名前", { ... }) で、設定 › Webhook で設定した Webhook に JSON を送るよう Vovó に頼めます。Discord のチャンネル、自動化、ネットワーク上のツールなどです。アドレスはこのコンピューターの保管庫に残り、バックアップにもパッケージにも入らず、アクションは名前しか知りません。Discord で告知の例でやり方がわかります。

受信 Webhook

反対に、インターネット上のサービスから Vovó に知らせることもできます。設定 › Webhook で受信 Webhook を作り、そのアドレスをコピーしてサービス（寄付ページ、ストア、スクリプト）に貼ります。呼び出しはそれぞれ webhook イベントとしてアクションに届き、hook（名前）と data（送られた内容）を持ちます。webhook トリガーに、hook がその名前であるという条件を付けて使います。Webhook ごとにアドレスがあるので、呼び出すサービスにだけ渡してください。リレーは呼び出しをこのコンピューター向けに封印して最大 1 日保管するので、Vovó が閉じているときの呼び出しも、開いたときに届きます。届くのは他人の書いたテキストです。アクションはテキストとしてだけ表示します。

このコンピューターのプログラムから

このコンピューターのプログラムは、知っていることをアクションに伝えられます。ゲームのログを読むスクリプト、大会のスコアを付けるツール、マクロなどです。アクションは action.json のトリガーの中に独自の名前のイベントを入れて待ちます（vovo dev が追跡するフォルダーと同じです）：

"triggers": ["score"]

そして他のイベントと同じように受け取ります：

vovo.on("score", (e) =>
{
    document.getElementById("home").textContent = e.home;
    document.getElementById("away").textContent = e.away;
});

プログラムは vovo emit に名前とフィールドを付けて伝えます：

vovo emit score home=2 away=1

数、true、false はそのまま、それ以外はテキストとして届きます。リストやオブジェクトは JSON でまるごと渡します。プログラムからはこう呼びます：

import json, subprocess
subprocess.run(["vovo", "emit", "score", "--fields", json.dumps({"home": 2, "away": 1})])

どのアクションが受け取ったかを伝え、どれも受け取らない場合は失敗します（終了コード 1、理由付き）。その名前をトリガーに持つアクションがない、条件を満たさない、開いているページがそれを表示していない、のいずれかです。行き先はアクション自身の vovo.emit と同じで、パニック中は送られず、10 秒に 30 回までです。操作ログには、コマンドラインが起動したと残ります。操作する人だけのアクションは受け取りません。プログラムが送るのはそのプログラムのテキストなので、アクションはテキストとしてだけ表示します。フォローなど API のイベントが起きたことにしたいときは、vovo simulate を使います。

プレビューとシミュレート

エディターは入力に合わせてアクションをライブで表示し、シミュレートボタンは本物を待たずにトリガーを発火させ、パッドのボタンと同じようにコントロールを動かします。プレビューのものは配信には何も届きません。コードやプレビューの隅のアイコンでウィンドウ全体に広げられ、同じアイコンか Esc で元の並びに戻ります。

スクリーンリーダー

スクリーンリーダーはコードエディターを読めません。コードの上のプレーンテキストボタンを押すと、その場所にテキストボックスが入り、ナレーター、NVDA、JAWS が全体を行・単語・文字ごとに読めます。Windows がスクリーンリーダーの動作を知らせているときは最初からオンです。Tab は次に移動するので、インデントはスペースで行ってください。

ファイル

エディターのファイルタブで、画像、音、動画、フォントを追加します。アクションは名前で使います：<img src="logo.png">。自分の音や動画を Web Audio（コンプレッサー、レベルメーター）に通すには、名前を渡す前に crossOrigin = "anonymous" で読み込んでください。アクションはすべてから切り離されて動くので、自分のファイルでさえ外から来たものになり、そうしないと Web Audio には無音に聞こえます。

権限

アクションが Vovó に頼めることは、動作の下にあります。チャットへの書き込み、Webhook の呼び出し、共有画面の表示、カメラの表示、OBS のソースの表示とフィルターのオンです。オフならアクションはそれができません。

アクションから OBS を

obs.toggle 権限があれば、vovo.obs.source("シーン", "ソース", true) で OBS のシーンのソースを表示し（false で非表示、省略すると切り替え）、vovo.obs.filter("ソース", "フィルター", true) でフィルターに同じことをします。名前は OBS のもので、大文字小文字やアクセントは区別しません。OBS にない名前はコンソールに、意図していたと思われる名前とともに表示されます。アクションが OBS でできるのはこれだけで、配信を止めたり、ストリームキーを読んだりはできません。

操作する人だけ

動作の「配信を操作する人だけ」をオンにすると、アクションはパッド、ホットキー、タイマー、そのコントロールからだけ起動します。視聴者、チャット、特典、Webhook、他のアクションのイベントからは決して起動しません。チャットを消す、シーンを切り替えるなど、見ている人にはできてはいけないことに使ってください。

バージョン

保存するたびにバージョンが残ります。「履歴」でどれにでも戻せます。

パッケージ

アクション一覧のエクスポートアイコンで、アクションをコードとファイルごと .zip に書き出し、人に渡せます。動作に書いた作者、サイト、何をするかの一行も一緒に入るので、取り込む人はそれが何でどこから来たかがわかります。「アクションをインポート」は、保存する前にパッケージの中身と求める権限を見せ、エディターでアクションを開きます。使う前に読んでください。手元のアクションと同じ名前のパッケージは、おそらくそのアクションの新しいバージョンなので、置き換えることを提案します。アクションはシーン、ボタン、状態を保ち、それまでのバージョンは履歴に残ります。ターミナルでは vovo export と vovo import で同じことができ、vovo import --replace は同じ名前のアクションを置き換えます。 人に渡すためのパッケージは、動作に ID を書けます。作った人の名前とアクションの名前を点でつないだものです（example.raffle）。こうしておくと、アクションの名前を変えたあとでも、次のバージョンが更新先のアクションを見つけ、作った人の違う同じ名前のアクションどうしが置き換わることもありません。vovo import --replace もこれに従います。ID があってもなくても、インポートはどのバージョンがどのバージョンと置き換わるかを示し、ファイルが同じバージョンか古いバージョンならそう知らせます。カスタマイズで選んだ内容は、新しいバージョンにその設定が残っているかぎり保たれます。 パッケージは、どのライセンスで渡すかを示せます。動作にライセンスの名前か自分の言葉を 1 行書き、ライセンスの全文は、そこでファイルから選ぶか、フォルダーの action.json の横に LICENSE として置きます。アクションを取り込む人はその 1 行を見て、アクションが入る前にインポートのダイアログから全文を読めます。Vovó は書かれたことを伝えるだけで、誰にも何も強制しません。キーもアカウントも購入も確認せず、アクションの販売は Vovó の外で行われます。 その横のコピーアイコンはアクションを複製し、コピーをエディターで開きます。動くものから派生版を作るためです。コード、ファイル、トリガーはコピーされますが、状態、シーン、ボタンはコピーされず、ホットキーのトリガーはキーの組み合わせなしでコピーされます。ひとつのキーで両方が起動しないようにするためです。

自分のエディターで

アクションは好きなエディターでも、自分のビルドでも書けます。パッケージと同じ構成（action.json、index.html、style.css、script.js、files/）でフォルダーに置き、ターミナルでそのフォルダーを指定して vovo dev を実行します。Vovó はその名前のアクションでエディターを開き（プロファイルになければフォルダーから作ります）、フォルダーで保存した変更をすぐプレビューに表示します。シミュレートもいつもどおり使えます。ここで入力した変更と同じく、保存するまで配信には届きません。vovo dev stop か、エディター上部の追跡を終了で、フォルダーを手放します。

vovo new <フォルダー> はそのフォルダーを用意します。空のもの、または例のどれかから作れます（vovo new --list で一覧、--from goal で 1 つを選択）。vovo check <フォルダー> は、フォルダーやパッケージの問題をすべて一度に伝え、何も作らず、何も開きません。問題ごとにファイルを示し、Vovó が受け取っても読み飛ばすもの（使わないキーなど）も伝えます。どちらも Vovó が閉じていても答えます。vovo export <アクション> <フォルダー> は、すでにあるアクションをそうしたフォルダーとして書き出します。

vovo dev はフォルダーに vovo.d.ts（この Vovó の API）も書き出し、jsconfig.json がなければそれも書き出します。これで VS Code などのエディターが vovo.、vovo.on(" のイベント名、各イベントのフィールドを補完します。どちらもアクションの一部ではなく、パッケージにも入りません。バージョン管理では、残すか無視するかお好みで。間違ったフィールドに下線を引かせたいときは、jsconfig の compilerOptions に "checkJs": true を加えます。

そこには action.schema.json も書き出します。これもアクションの一部ではありません。action.json の先頭に "$schema": "./action.schema.json" と書くと、エディターがキーを補完し、イベントや権限を名前で候補に出し、Vovó が拒否する内容に下線を引きます。

プレビューはブラウザーでも開けます。vovo dev が表示するアドレスか、プレビューの隅の矢印からです。同じ下書きを配信と同じ vovo が実行し、変更のたびに再読み込みされ、シミュレートも届き、ブラウザーの開発者ツール（コンソール、ブレークポイント、要素）も使えます。

• action.json と pad.json

配信に表示するには

アクションはシーンに入っている必要があり、そのシーンは OBS に入っている必要があります。

• シーンと OBS