適切な作成パスを選択

構築の様子を見る

フィルム / SDK でキオスクアプリを構築

3:07

開始 のセッション設定後に screenrig を使用してください。

コンテンツパスを選択

生成はアートワークと文字を一緒にレイアウトするため、すべての文言をプロンプトに入れてください。カードはPlayer内でテキストを描画するので、単語や数値が変わっても新しい静止画は不要です。用意済みの完成アセットに生成は不要です。アニメーションだけでは、どちらも必要になりません。

完成静止画を生成

エージェントはプロンプトと aspect_ratio と quality を送信します。screenRIG はアカウントのメディアストアに med_… メディアオブジェクトを返します。呼び出し元はバイトを再アップロードしません。検査のために元のバイトを取得し、それ以外はプレイリスト内で med_… 参照を保持してください。

ご自身の media upload は有効なままです。すでにファイルがある場合は生成しません。ライブビデオ、ストリーム、iframe、Webアプリページはプレイリストのプリミティブであり、生成された静止画ではありません。

品質はlow、medium、またはhigh（デフォルトはmedium）です。アスペクト比は1:1、16:9、9:16、4:3、3:4、3:2、または2:3（デフォルトは16:9）です。--qualityは静止画の詳細度と使用トークン数を変えます。

media generate --prompt TEXT [--aspect-ratio RATIO] [--quality QUALITY] [--tag TAG]

screenrig media generate --prompt "A 16:9 restaurant menu poster for North Lobby Cafe. Dark walnut, gold type. Title NORTH LOBBY CAFE. Items: Espresso $4, Cortado $4.50, House Blend $3. Footer Open 7am to 7pm. Typeset every line of copy in the image." --aspect-ratio 16:9 --quality high --tag LobbyMenu

エンベロープはmed_… IDを報告します。画像バイトは表示しません。

{
  "ok": true,
  "data": {
    "id": "med_01EXAMPLEGENERATED0000000",
    "media_id": "med_01EXAMPLEGENERATED0000000"
  }
}

サウンドトラックを追加

プレイリストは1つのサウンドトラックを持てます：MP3トラックの順序付きリストで、ページが変わっても連続再生されます。ページ遷移は音楽を停止、再起動、フェードしません。サウンドトラックはプレイリスト設定であり、キャンバス上の7番目のプリミティブではないため、矩形やレイヤーはありません。

media uploadで各トラックをアップロードします。MP3ファイルはそのままアップロードされます。WAV、AAC、M4A、OGG、FLACファイルは最初にMP3にトランスコードされます。各トラックはaudioメディアオブジェクトとなり、med_…のIDと再生時間を持ちます。

screenrig media upload ./intro.mp3 --tag LobbyMusic
screenrig media upload ./bed.wav --tag LobbyMusic

プレイリストのトラックに名前を付けます audio メンバーは1～128トラックを保持します。トラックは順番に連続再生されます。loop（デフォルトは true）は最後のトラック後に最初に戻り、volume（デフォルトは 1、0から1の範囲）は Player の音量を調整します。

{
  "name": "Lobby",
  "audio": {
    "tracks": [
      { "id": "intro", "media_id": "med_01EXAMPLEINTRO000000000" },
      { "id": "bed", "media_id": "med_01EXAMPLEBED00000000000" }
    ],
    "loop": true,
    "volume": 0.8
  },
  "pages": [
    { "id": "welcome", "audio_cue": { "track": "intro", "restart": true } },
    { "id": "menu" }
  ]
}

ページは任意の audio_cue を持つことがあります。そのページが表示されると、Player は指定されたトラックを開始位置から再生します。すでに再生中の場合、restart が true のときのみ再起動します。シーケンスはキューされたトラックから続行されます。キューはヒントであり、Player は短いフェードで適用するか、トラックが準備できていなければスキップします。キューなしページは音楽を変更しません。id と audio_cue 以外のページフィールドは上記例から省略されています。

プレイリストを置き換えるとサウンドトラックも置き換わります。削除するにはaudioを除いてください。キャンバス上のビデオはミュートのままなので、サウンドトラックだけがスクリーンで再生されます。

トラックにページをバインド

アルバムや本で各トラックごとに1ページ、またはトラックの長さと同じだけ表示するページの場合は、そのページをトラックに紐付けてください。

ページ advance を { "mode": "audio_end" } に設定します。ページは表示時に audio_cue を適用し、キューと同様に動作し、トラック終了時に終了します。media_end ページが動画終了で終わるのと同様です。ページは audio_cue を持ち、プレイリストは audio サウンドトラックを持つ必要があります。画像と動画プリミティブは duration ルールに従います：dwell_ms はなく、one_at_a_time: true はすべての動的セレクター（all、tag、folder、または複数IDの ids）に適用されます。stream プリミティブは依然として duration ページを必要とし、ページ上のアプリは制御者ではありません。max_ms は任意の安全ヒントで、サーバーはトラック長から期限を設定するため省略可能です。プレーヤーがトラックを再生できない場合もページはトラック長だけ持続します。

cued を true に設定し、audio メンバーで各トラック後にサウンドトラックを停止します。キューされたトラックはページ audio_cue が開始したときのみ再生されます。続く通常ページの間は再生を続け、終了後は次のキューまで無音になります。これによりページとトラックが結びつき、結びついたページ間に任意の数の通常ページが存在できます。loop はキューされたサウンドトラックに影響せず、cued はデフォルトで false です。

{
  "name": "Album",
  "audio": {
    "tracks": [
      { "id": "song1", "media_id": "med_01EXAMPLESONG1000000000" },
      { "id": "song2", "media_id": "med_01EXAMPLESONG2000000000" }
    ],
    "cued": true
  },
  "pages": [
    { "id": "song1-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song1", "restart": true } },
    { "id": "interlude", "advance": { "mode": "duration", "after_ms": 8000 } },
    { "id": "song2-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song2", "restart": true } }
  ]
}

id、advance、audio_cue以外のページフィールドは上記の例から省略されています。

ライブテキスト用のカードを配置

組み込みカードは、テキスト、メニュー、表、時計、ゲージを Player 自身が描画します。そのためテキストは編集可能なままで、新しい値は新しい静止画なしですべてのスクリーンに届きます。cards list は種類を表示し、card create はインスタンスを作成し、プレイリストはそれを card プリミティブとして配置します。card data put はそのライブ値を書き込みます。カードでは、すべての種類とレイアウトを確認できます。

screenrig cards list
screenrig card create --type gauge --file gauge-params.json
screenrig card data put crd_EXAMPLE --file gauge-data.json

サインインが必要なダッシュボードを表示する

Web 接続は、人と同じようにサービスアカウントでサイトにサインインし、Web ビューはそのサイトの 1 ページを表示します。Salesforce、Looker Studio、Datadog、HubSpot など、公開リンクのないサイトのダッシュボードに向いています。screenRIG のエッジにあるブラウザーがサインインした状態でページを開き、Player はその画像を表示します。画像は refresh_s 秒ごと (60 〜 86,400、デフォルトは 300) に描き直されます。同じサイズのすべてのスクリーンが 1 つの画像を共有するため、スクリーンを増やしてもサインインは増えず、画像はスクリーンのプレイリストがそのビューを表示している間だけ描画されます。Grafana、Power BI、Tableau の接続とビューも同じように動作し、API リファレンスに記載されています。

1. サイトにサービスアカウントを作成し、スクリーンが表示するダッシュボードだけを読み取れるようにします。すべてのキャプチャはそのアカウントでサインインします。
2. 接続を作成します。kind web と下記の設定を指定し、パスワードは secret に入れます。
3. ビューを作成します。1 ページ分の https アドレスを url に、そして wait_for には、ページがサインイン済みで準備できているときだけ現れる要素の CSS セレクターを指定します。これにより、サインインページが描画されるのではなくタイムアウトになります。clip はセレクターで指定した部分だけを描画し、wait_ms (最大 10,000) は遅れて表示されるグラフを待ちます。
4. ビューの embed_url を、content_fit fill の iframe プリミティブに置きます。

{
  "kind": "web",
  "name": "Sales dashboard",
  "config": {
    "login_mode": "auto",
    "login_url": "https://login.example.com/sign-in",
    "username": "screens@example.com"
  },
  "secret": "ACCOUNT_PASSWORD",
  "totp_secret": "AUTHENTICATOR_KEY"
}

{
  "connection_id": "bic_01EXAMPLECONNECTION0000",
  "name": "Sales this week",
  "url": "https://app.example.com/dashboards/sales",
  "refresh_s": 300,
  "wait_for": "#sales-total"
}

パスワード、TOTP キー、クッキーは config と並べて指定し、封印して保存され、二度と表示されません。読み取りでは、それぞれが設定されているかどうかが示されます。secret または totp_secret を空にするか、cookies: [] を指定すると削除されます。

• まずクッキー。 接続は封印したクッキーセットを 1 つ保持します。貼り付けたもの、そして各キャプチャが返すクッキーです。キャプチャはクッキーセットを送り、認証情報は送らず、クッキーセットがないとき、または直前のキャプチャがサインインページに行き着いたときだけサインインします。セッションをクッキー以外で保持するサイトは、キャプチャのたびにサインインするため、そのビューには長い refresh_s を設定してください。
• パスワードが行くのはサインインページだけです。 パスワードは login_url と goto ステップでのみ入力され、ビューのアドレスには決して入力されません。どちらかにアドレスを追加するには、同じリクエストにパスワードが必要なので、パスワードを読み取れないメンバーが、自分のページにパスワードを向けることはできません。
• アカウントは保護されます。 拒否されたサインイン (bi_web_login_failed または bi_web_otp_required) は 5 分待ち、続いて 15 分、60 分、120 分待ちます。5 回連続すると、認証情報またはサインイン設定を変更するまで接続が停止するため、最初の 1 時間に行われる試行は最大 3 回です。それ以外の理由で終わったサインイン (タイムアウト、ブロック、開けなかったページ) は 15 分待ちます。読み取り専用のサービスアカウントを使ってください。
• スクリプトにできないサイトもあります。 電話でサインインを承認するサイト、デバイスを確認するサイト、CAPTCHA を表示するサイトには、クッキーセット (login_mode none)、またはサイトが除外するサービスアカウントが必要です。

キャプチャが失敗している間、Player は最後の正常な画像を保持し、ビューのステータスには次のいずれかのコードが示されます:

screenrig bi connection test ID はサインインして結果を報告します。接続の session は、クッキーとサインインの状態を示します: idle、active、login_needed、paused、stopped、expired のいずれかです。

タグフィルターと再生バッチ

メディアは最大32個のユニークタグを持ち、それぞれ1～32文字の英数字です。セット全体をscreenrig media update med_ID --tags Summer,Drinksで置き換えます。--tag Summerは1つのタグで置き換え、--clear-tagはすべてのタグをクリアします。media list --tag Summerはセット内のどこかのメンバーシップに一致します。タグは大文字小文字を区別し、承認には使用されません。

動的セレクターは1つの tag または tags フィルターオブジェクトを使えます：

{
  "by": "tag",
  "tags": { "all": ["Summer", "Drinks"], "any": ["Lobby", "Patio"], "none": ["Expired"] },
  "order": "random",
  "one_at_a_time": false,
  "batch_size": 3
}

all はすべての指定タグが必須、any はいずれか 1 つが必須、none は指定タグを除外します。グループ同士は AND で組み合わされ、指定しないグループは条件を課しません。少なくとも 1 つの空でないグループを指定してください。各グループは最大 32 個のユニークなタグを受け付けます。tag と tags は同時に使えません。none のみのフィルターは、除外タグ以外のその種別のすべての準備済みメディアを選択します。画像セレクターは画像を、動画セレクターは動画を選択します。

候補プールにはセレクターごとに最大1,024件の準備済みメディアが含まれ、ループ全体のスナップショットで1,024件のメディア参照があります。より大きな一致はエラーを返します。フィルターを絞ってください。batch_size はページ訪問ごとの1～1,024件の別の制限です。media_end ページでは、one_at_a_time: false が次のバッチを順に再生し、batch_size を省略すると残りのパスを再生します。one_at_a_time: true は出現ごとに1件を再生し、省略されたバッチサイズまたは batch_size: 1 のみを許可します。期間、アプリケーション、および audio_end ページには one_at_a_time: true が必要です。media_end の画像も dwell_ms が必要で、動画はそのページでループできません。

Player はプレイリストの開始時と各ループ境界で、すべての動的メディアプリミティブを 1 回のリクエストで解決します。メンバーシップはループ中に固定されます。アップロード、削除、タグ変更、利用可能期間の境界はマニフェストを再生成しません。次の更新時に削除または新たに除外されたアイテムは保留キューから外れ、新しいマッチは現在のパス終了時に参加します。最終バッチは要求数より少ない場合があり、次のパスから補充しません。ファイル名順はファイル名、次にメディア ID でソートします。ランダム順は完全なパスごとに一度シャッフルし、残りの順序をループ更新間で保持します。重み付き順は、後述の重みに従います。カーソルは画面、プレイリスト、ページ、プリミティブにローカルで、再起動をまたいで持続し、フィルター、順序、バッチポリシー変更時にリセットされます。オフライン再生は最後に成功したスナップショットを使用します。空のマッチはプリミティブと結果としての空ページをスキップします。

上記のセレクターオブジェクトをselector.jsonとして保存し、公開前に現在の候補カタログを検査してください：

screenrig media selector-preview selector.json --primitive video

プレビューはmatched_count、ファイル名順のcandidates（メディアIDとタグ付き）、正規化されたselectorポリシーを返します。ランダム順ではプールとシャッフルポリシーを表示しますが、プレーヤーのシャッフルを選択したり、カーソルを進めたり、再生許可を作成したり、マニフェストを変更したりしません。重み付き順では、各候補のweightとshare_percent、およびcycleを返します。--rect WxH（API ではrect: {width, height}）はスロットのサイズで、fit: "aspect"では必須です。除外された一致はexcludedに理由aspect_mismatch付きで一覧表示されます。画像セレクターは--primitive imageを渡します。APIはPOST /api/selectors/previewで{ "primitive": "video", "selector": ... }と連携します。認証済みのプロジェクトと再生と同じマッチングルールを使用します。プレビュー後のカタログ変更は再生の次のループ境界で解決されます。

静的バンドルのエクスポートは動的マッチを正確な ID として固定します。1つずつまたは完全なパスの再生を保持します。batch_size と one_at_a_time: false を使う制限付きランタイムシーケンスは、エクスポート前にそのフィールドを削除するか明示的な ID を選択する必要があります。これにより静的バンドルでランタイムバッチカーソルが失われるのを防ぎます。

重み付きローテーションとアスペクト調整

order: "weighted"は、1 つのスロットのクリエイティブを重みに応じてローテーションし、各スポンサーが再生回数のシェアを維持できるようにします。weightsは、メディア ID（med_...）またはtag:NAMEを 1 から 1,000 の整数に対応付け、キーは最大 64 個です。byがall、tag、folderのいずれの場合にも使えます：

{
  "by": "all",
  "order": "weighted",
  "one_at_a_time": true,
  "weights": { "tag:Acme": 50, "tag:Globex": 30, "tag:Initech": 20 },
  "fit": "aspect"
}

重み 50、30、20 は、毎サイクル、10 回の再生のうちちょうど 5 回、3 回、2 回になり、再起動はサイクルの途中から再開します。アイテムの重みは、そのメディア ID のキーがあればその値、なければ所持するタグのうちアルファベット順で最初のtag:NAMEキーの値で、そのキーを持つ選択内のアイテムで均等に分割されます。そのため、クリエイティブの数にかかわらずスポンサーのシェアは保たれます。どちらもない場合、アイテムは重み 1 の単独グループとして扱われます。1 サイクルは最大 4,096 回の再生で、正確な比率がそれより長いサイクルを必要とする場合にのみ、シェアはそこに丸められます。

重み付き順は 1 回の表示で 1 アイテムを再生するため、one_at_a_time: trueまたはbatch_size: 1を設定します。weightsは重み付き順で必須で、重み付き順でのみ使えます。それ以外では書き込みがinvalid_requestを返します。Web、Android、Apple、Windows、Linux の Player は、ホスト機能selector.weightedを宣言するリリースから重み付き順に対応します。それより古い Player はセレクターをランダム順で再生し、マニフェストの診断にはselector_order_downgradedが含まれます。

動的セレクターのfit: "aspect"は、幅と高さの比がスロットの矩形（ビデオウォールやディスプレイフレームを含む）の比の 5% 以内にあるファイルだけを残します。セレクターの解決時に読み取られます。縦向きのスロットで横向きのファイルが再生されることはありません。Player の変更は不要です。

screenrig media selector-preview は、重み付きまたはアスペクト調整されたすべてのセレクターの想定シェアを表示し、ダッシュボードのページエディターもインスペクターで同じ表を表示します。静的バンドルのエクスポートは、重み付きセレクターをファイル名順の正確な ID として固定し、重みは保持されません。

タグセレクターでの画面トークン

タグセレクターのtagと、そのtagsフィルターの各エントリには、{screen.field.NAME}または{screen.id}（scr_プレフィックスを除いた画面の識別子で、タグになります）を使えます。サーバーは、各画面のマニフェストとセレクターのスナップショットを作成するときにその画面のトークンを埋めるため、1 つのプレイリストで各画面専用のメディアを再生できます。メディアにLobbyまたはGarageのタグを付け、screenrig screen update scr_ID --field zone=Lobbyで各画面のフィールドを設定し、スロットに次のセレクターを指定します。

{ "by": "tag", "tag": "{screen.field.zone}", "one_at_a_time": true }

埋められた値はタグの規則（1～32 文字の英数字）に従います。フィールドがない画面、または値がタグでない画面は何も選択せず、そのスロットからはファイルを再生せず、マニフェストの診断にscreen_fact_missingまたはscreen_fact_invalidが含まれます。フィールドを変更すると、その画面のマニフェストが再発行されます。トークンを含むセレクターはプレビューできず（media selector-previewには具体的なタグが必要です）、playlist exportで固定することもできません。

iframe アドレスとアプリケーションの params のスクリーントークン

iframe の src と fallback_src には、http または https アドレスのパス、クエリ、フラグメントにスクリーントークンを含めることができ、application プリミティブの任意の params にも含められます。トークンは、小文字の英字、数字、アンダースコアからなる1〜32文字の名前を最大16個まで（ticket と policy は予約済み）、値は512文字までです。サーバーがスクリーンごとに値を埋め込みます:

{
  "primitive": "iframe",
  "src": "https://maps.example.com/directory?kiosk={screen.field.kiosk_id}&level={screen.field.level}",
  "title": "Directory"
}

書き込みは、テンプレートを波括弧を含めてそのまま保存します。各スクリーンのマニフェストは、URL 内の位置に合わせてすべての値をパーセントエンコードした、そのスクリーン専用のアドレスを持ちます。B 2&3 の kiosk_id は B%202%263 になります。スキーム、認証情報、ホスト、ポート、または YouTube リンク、Google や Microsoft のドキュメントリンク、BI ビューアドレス内のトークンは、src（または fallback_src）で invalid_request です。テンプレート化された src では、公開時にフレーム表示のチェックを行わず、プレビューにはテンプレートがそのまま表示されます。

値が欠けている（未設定のフィールド、位置情報なし）、または値を埋め込んだアドレスが2048文字を超える、もしくはパスセグメントが . または .. になるスクリーンには、そのような iframe やアプリケーションは設定されず、そのマニフェストの診断に screen_fact_missing または screen_fact_invalid が含まれます。空になったページは削除されます。そのようなスクリーンに反映されるすべての書き込み（プレイリストの書き込み、screen assign、screen update、フリートの割り当て、承認されたレビュー）は、トークン、最初の20件のスクリーン ID、および総数を示す screen_fact_missing 警告を返します。フィールドまたは位置情報を変更すると、影響を受けるスクリーンのマニフェストが再発行されます。

アプリケーションでは、埋め込まれた各パラメーターが ticket の後ろに、パーセントエンコードして合計4096文字までで起動アドレスに付加されるため、アプリケーションは location.search（SDK）から読み取れます。起動パラメーターは Player ウェブアプリと、それを実行する Player（Samsung Tizen、BrightSign、LG webOS、Vega）に届きます。Qt、Android、Apple、Windows の Player はローカルパッケージからアプリケーションを読み込み、パラメーターを送りません。テンプレートの url フィールドは iframe 全体の src にでき、その値自体がスクリーントークンを含んでもよく、マニフェストの作成時に埋め込まれます。タグセレクターは {screen.id} と {screen.field.NAME} を同様に使います（上記）。カードは独自の {screen.…} トークンを保持します。

メディアの利用可能期間

screenrig media availability med_ID --file rule.jsonは、動的セレクター（all、tag、folder）がファイルを選べる時期を設定します。--clearはルールを削除し、--expect-rev Nはメディアのリビジョンを保護します。API はPATCH /api/media/{id}/availabilityで、If-Matchと{ "availability": {...} | null }を使います。ルールの設定には Manage アクセスが必要で、Propose 資格情報にはinsufficient_accessが返ります。

ルールはスケジュールの時刻文法で、各画面のタイムゾーンで解釈され、少なくとも 1 つの要素を含みます。fromとuntil（ローカル日時YYYY-MM-DDTHH:MM、untilは終了を含まない）、windows（毎週の{days, start, end}）、monthly（{day}または{nth, weekday}、それぞれに任意のstartとend）、dates（{date, start, end}）、except（発生を取り除く日付で、日をまたぐ部分を含む）です。dataとinteractionは使えません。連休中のスポンサーのクリエイティブを、期間内の平日の夜だけ利用可能にする例です。

{
  "from": "2026-11-27T00:00",
  "until": "2026-11-30T23:59",
  "windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "17:00", "end": "22:00" }]
}

ルールを読むのはセレクターだけです。明示的なidまたはidsセレクターは無視し、カードのメディア参照、サウンドトラックの音声、広告クリエイティブも対象外です。ファイルは、各画面の次のプレイリストループで選択から外れたり戻ったりし、境界から約 1 分以内に反映されます。プレイリストやマニフェストのリビジョンは変わらず、オフラインの Player は再接続するまで最後の選択を保持します。screenrig media selector-preview --timezone ZONE（既定は UTC）は、その時点でルールの範囲外にあるファイルを理由outside_window付きでexcludedに一覧表示します。

screenRIG CLIリファレンスに戻ります。