OBS Lua 高機能イベントタイマー - sokudon/miku GitHub Wiki
OBS Lua 高機能イベントタイマー スクリプト ドキュメント （gemimipro2.5生成）
このLuaスクリプトは、OBS Studioのテキストソースを使用して、イベントの開始/終了時刻に基づいた高度なタイマー機能を提供します。経過時間、残り時間、イベント期間、進捗率、現在時刻（ローカル、UTC、JST、指定タイムゾーン）などを柔軟な書式で表示できます。
元となったスクリプト/参考情報:
- オリジナルタイマー: Advanced Timer by universal_quantifier
- JSONパーサー参考: gist by zwh8800
- 旧版 (残り時間のみ): sokudon/deresute/OBSdere.lua (旧コミット)
- パラメータWiki (参考): sokudon/deresute Wiki
- タイムゾーンデータ概念: Moment Timezone (特にAmerica/Los_Angelesのデータ構造を参考に実装)
- TZIFパーサー概念: luatz (requireを使用しない形に改造して統合)
主な機能
- イベントの開始時刻と終了時刻に基づくタイマー表示。
- 経過時間、残り時間、イベント期間の表示（カスタム書式対応）。
- イベント進捗率（パーセント）と進捗バーの表示。
- 現在時刻の表示（OS依存ローカル、UTC、JST、指定IANAタイムゾーン）。
- 開始/終了時刻の表示（OS依存ローカル、UTC、JST、指定IANAタイムゾーン）。
- 豊富な日時・期間フォーマット指定子。
- 多様な日時入力形式に対応 (ISO 8601、YYYY/MM/DD HH:MM TZ、RFC 2822、Unixタイムスタンプ、ローカル時刻など)。
- IANAタイムゾーン名によるタイムゾーン指定とTZ Database (zoneinfo/tzdata) ファイルの自動検索・読み込み。
- POSIX TZ文字列によるフォールバック（TZ Databaseファイルが見つからない場合や将来の時刻）。
- OBSの配信/録画開始・停止イベントとの連携（モードによる）。
- タイマーリセット、一時停止/再開のホットキー対応。
- テキストソースへの自動更新。
インストール方法
- OBS Studioを開きます。
- メニューから
ツール>スクリプトを選択します。 スクリプトタブの左下にある+ボタンをクリックします。- ダウンロードした
.luaファイルを選択して追加します。 - スクリプトがリストに追加され、右側に設定項目が表示されます。
設定項目 (スクリプトUI)
スクリプトを選択すると、以下の設定項目が表示されます。
- Mode: タイマーの動作モード（現在は
Countdown固定の可能性あり、元のスクリプトには他のモードも存在）。 - WorldTime UTC+-?? (UTC): UTCからのオフセットを指定する古い方法（主に表示用、タイムゾーン指定が優先される）。
- TIMEZONE: タイマー計算や表示に使用するIANAタイムゾーン名（例:
America/Los_Angeles,Asia/Tokyo,UTC）。リストから選択または直接入力。 - Text Source: タイマーのテキストを表示するOBS内のテキストソース（GDI+ または Freetype 2）を選択します。
- EVENT NAME (Title Text): イベントのタイトル (
%Tで使用)。 - START (Start Text): イベントの開始日時。ISO 8601形式 (
YYYY-MM-DDTHH:MM:SS+HH:MMやYYYY-MM-DDTHH:MM:SSZ) を推奨。他の形式も解釈可能（後述）。 - END (Stop Text): イベントの終了日時。同上。
- ELASPED/LEFT format (Format): 経過時間 (
%K)、残り時間 (%L)、イベント期間 (%I) を表示する際の書式（後述の「期間/間隔 書式」参照）。 - TIME parameter (Para Text): テキストソースに最終的に表示する内容のテンプレート。利用可能なプレースホルダ（後述）を組み合わせて記述します。
- TIME format (Time Text):
%N,%UTC,%JST,%TZ,%S,%E,%SJ,%EJなどで日時を表示する際の書式（後述の「日時 書式」参照）。 - STOP text (End Text): イベント終了後に残り時間 (
%L) の代わりに表示するテキスト（空欄の場合は期間0を表示）。 - PROGRESSBAR (Bar): 進捗バー (
%Q) の解像度（100をここで指定した値で割った段階数で表示。例: 2なら50段階）。 - Activation mode (a_mode): タイマーをいつアクティブにするか（Global:常に、Start timer on activation:ソース表示時に開始/リセット）。
- Start/Pause Button: スクリプトUIからタイマーを開始/一時停止します。
- Reset Button: スクリプトUIからタイマーをリセットします。
- tzpath: TZ Database (zoneinfo/tzdata) ファイルが格納されているディレクトリのパス。通常は自動検出されますが、必要に応じて手動で指定できます。リストから候補を選択または直接入力。
プレースホルダ (TIME parameterで使用)
一般
| プレースホルダ | 説明 |
|---|---|
%T |
イベント名・タイトル (EVENT NAME設定) |
%P |
イベント進捗率 (%) (小数点以下2桁) |
%Q |
イベント進捗バー ([===>_____]形式) |
日時表示
TIME format 設定で指定した書式に従って表示されます。
| プレースホルダ | 説明 |
|---|---|
%N |
現在時刻 (OS依存のローカル時刻) |
%UTC |
現在時刻 (UTC) |
%JST |
現在時刻 (日本標準時 JST, UTC+9) |
%TZ |
現在時刻 (設定されたTIMEZONEの時刻) |
%TZN |
現在時刻 (設定されたTIMEZONEの時刻、os.date非依存実装) |
%S |
イベント開始時刻 (OS依存のローカル時刻) |
%E |
イベント終了時刻 (OS依存のローカル時刻) |
%SU |
イベント開始時刻 (UTC) |
%EU |
イベント終了時刻 (UTC) |
%SJ |
イベント開始時刻 (日本標準時 JST) |
%EJ |
イベント終了時刻 (日本標準時 JST) |
%SS |
イベント開始時刻 (設定されたTIMEZONEの時刻) |
%EE |
イベント終了時刻 (設定されたTIMEZONEの時刻) |
%EXP |
TZ Databaseの有効期限 (存在する場合、TIMEZONEでの時刻表示) |
%% |
% 文字自体 |
%n |
改行 |
%t |
水平タブ |
日時 書式 (TIME format 設定で使用。os.date準拠 + カスタム)
| 書式 | 説明 | 例 (Asia/Tokyo) |
|---|---|---|
%Y |
年 (4桁) | 2025 |
%m |
月 (01-12) | 03 |
%d |
日 (01-31) | 29 |
%H |
時 (24時間形式, 00-23) | 14 |
%M |
分 (00-59) | 33 |
%S |
秒 (00-59) | 09 |
%a |
曜日 (省略形) | Sat |
%A |
曜日 (完全形) | Saturday |
%b |
月 (省略形) | Mar |
%B |
月 (完全形) | March |
%z |
タイムゾーンオフセット (+HHMM または -HHMM形式) | +0900 |
%Z |
タイムゾーン略称 (例: PST, JST, UTC) ※%TZN専用実装 |
JST |
%c |
ロケール依存の日時表現 | Sat Mar 29 14:33:09 2025 |
%x |
ロケール依存の日付表現 | 03/29/25 |
%X |
ロケール依存の時刻表現 | 14:33:09 |
%Y-%m-%dT%H:%M:%S%z (%a) |
ISO 8601風のカスタム書式例 | 2025-03-29T14:33:09+0900 (Sat) |
(その他 os.date の書式指定子) |
注意: Windows環境では os.date の %Z, %z の挙動に制限があるため、%TZ, %TZN, %SS, %EE など、スクリプト内部でタイムゾーン処理を行うプレースホルダの使用が推奨されます。%TZN は os.date を使わずにタイムゾーン略称(%Z)とオフセット(%z)を含む書式を処理します。
期間/間隔 書式 (ELASPED/LEFT format 設定で使用)
| 書式 | 説明 | 例 |
|---|---|---|
%d |
日数 (切り捨て) | 3 (3日と5時間の場合) |
%H |
総時間数 (切り捨て) | 77 (3日と5時間の場合) |
%M |
総分数 (切り捨て) | 4620 |
%S |
総秒数 (切り捨て) | 277200 |
%h |
時間 (24時間以内、切り捨て) | 5 (3日と5時間の場合) |
%m |
分 (60分以内、切り捨て) | 15 |
%s |
秒 (60秒以内、切り捨て) | 30 |
%t |
ミリ秒 (1/10秒) | 5 (3.5秒の場合) |
%hh |
時間 (24時間以内、2桁ゼロ埋め) | 05 |
%mm |
分 (60分以内、2桁ゼロ埋め) | 15 |
%ss |
秒 (60秒以内、2桁ゼロ埋め) | 30 |
%HH |
総時間数 (2桁ゼロ埋め) | 77 |
%MM |
総分数 (2桁ゼロ埋め) | 4620 |
%SS |
総秒数 (2桁ゼロ埋め) | 277200 |
%ds |
総日数 (小数点以下3桁) | 3.208 |
%hs |
総時間数 (小数点以下3桁) | 77.000 |
%ms |
総分数 (小数点以下3桁) | 4620.000 |
書式例: %d日 %hh:%mm:%ss -> 3日 05:15:30
日時入力形式 (START/END)
以下の形式での日時入力を解釈しようと試みます。
- ISO 8601 (推奨):
YYYY-MM-DDTHH:MM:SS+HH:MM(例:2025-03-29T15:00:00+09:00)YYYY-MM-DDTHH:MM:SSZ(例:2025-03-29T06:00:00Z) (UTC)YYYY-MM-DDTHH:MM(秒、オフセットは補完)
- Unixタイムスタンプ:
1743212400(秒)
- RFC 2822風:
DD Mon YYYY HH:MM:SS TZ(例:29 Mar 2025 15:00:00 JST)DD Mon YYYY HH:MM TZ(例:29 Mar 2025 15:00 PST)DD Mon YYYY HH TZ(例:29 Mar 2025 15 +0900)DD Mon YYYY TZ(例:29 Mar 2025 UTC)
- 区切り文字違い/ローカル:
YYYY/MM/DD HH:MM TZ(例:2025/03/29 15:00 JST) ※UU とTZ拡張ありYYYY-MM-DD HH:MM TZ(例:2025-03-29 15:00 PST)YYYY/MM/DD HH:MM:SS(ローカル時刻として解釈)YYYY-MM-DD HH:MM(ローカル時刻として解釈)YYYY-MM-DD HH(ローカル時刻として解釈)YYYY-MM-DD(ローカル時刻の0時として解釈)
タイムゾーン指定子 (TZ):
+HHMMor-HHMM(例:+0900,-0800)Z(UTC)UUWorldTime UTC+-??オフセットの値useTZ,TZ,LA(内部で使用): 設定されたTIMEZONE(America/Los_Angelesなど) として解釈するための特殊な指示子。入力例:2025-03-10 03:00 useTZ- タイムゾーン略称 (例:
JST,PST,PDT,UTC,GMT) - スクリプト内部のテーブルまたはTZ Databaseの情報に基づいて解釈されます。一部小文字かぶるので - ACDT +1030
- ACST +0930
- AEDT +1100
- AEST +1000
- AFT +0430
- AKDT -0800
- AKST -0900
- ART -0300
- AWDT +0900
- AWST +0800
- BDT +0600
- BNT +0800
- BOT -0400
- BRT -0300
- BST +0100
- BTT +0600
- CAT +0200
- CCT +0630
- cDT -0400
- CDT -0500
- CEST +0200
- CET +0100
- CLST -0300
- CLT -0400
- COT -0500
- cst +0800
- cST -0500
- CST -0600
- ChST +1000
- EAT +0300
- ECT -0500
- EDT -0400
- EEST +0300
- EET +0200
- EST -0500
- FJST +1300
- FJT +1200
- GMT +0000
- GST +0400
- HKT +0800
- HST -1000
- ICT +0700
- IDT +0300
- iST +0200
- IST +0530
- IRDT +0430
- IRST +0330
- JST +0900
- KST +0900
- MDT -0600
- MMT +0630
- MST -0700
- MYT +0800
- NPT +0545
- NZDT +1300
- NZST +1200
- PDT -0700
- PET -0500
- PHT +0800
- PKT +0500
- PST -0800
- PWT +0900
- SST -1100
- UT +0000
- UTC +0000
- UYT -0300
- WAT +0100
- WEST +0100
- WET +0000
- WIB +0700
- WIT +0900
- WITA +0800
注意: タイムゾーン指定がない場合は、OSのローカルタイムゾーンとして解釈される可能性があります。曖昧さを避けるため、ISO 8601形式でのUTCオフセット指定 (+HH:MM or Z) または、信頼できるタイムゾーン略称 (JST, PST/PDT) の使用を推奨します。IANA名 (Asia/Tokyo) を直接入力する形式は現在サポートされていないようです。代わりにTIMEZONE設定を使用してください。
タイムゾーン処理詳細
- TZ Database (zoneinfo/tzdata): スクリプトは一般的なパス (Windows/Unix) を検索し、
zoneinfoディレクトリまたはtzdataファイルを見つけようとします。見つかった場合、指定されたTIMEZONEのTZIFバイナリファイルを解析し、正確なUTCオフセットと夏時間(DST)の遷移情報を使用します。tzpath設定でパスを手動指定することも可能です。 - POSIX TZ 文字列: TZ Databaseファイルが利用できない場合や、ファイルの有効期限を超える将来の日時については、TZIFファイル内に含まれるPOSIX TZ文字列（例:
PST8PDT,M3.2.0,M11.1.0）に基づいてオフセットとDSTを計算しようと試みます。 - Moment Timezone データ: スクリプト内部に
America/Los_Angelesの過去～未来約10年分のタイムゾーン遷移情報 (UTCオフセット、略称、遷移時刻) がMoment Timezoneのデータ形式に似た形でハードコードされており、TZ Databaseが見つからない場合のフォールバックや、特定のタイムゾーン処理に使用されることがあります。
ホットキー
OBSの 設定 > ホットキー で、以下の操作にホットキーを割り当てることができます。
- Reset Timer: タイマーを初期状態（カウントダウンなら設定された残り時間、カウントアップなら0）にリセットします。
- Start/Stop Timer: タイマーを開始または一時停止/再開します。
注意事項
- テキストソース: 設定で指定したテキストソースが存在しない場合、更新は行われません。
- 日付/時刻のパース: 多様な形式に対応しようとしていますが、予期しない形式や曖昧な入力では正しく解釈できない場合があります。ISO 8601形式が最も安全です。
- タイムゾーンファイル: 正確なタイムゾーン処理のためには、システムのどこかに
zoneinfoまたはtzdataファイルが存在することが望ましいです。PythonやCygwin、WSLなどをインストールしている場合、それらのパスから自動検出されることがあります。 - パフォーマンス: 頻繁なテキスト更新はOBSのパフォーマンスに影響を与える可能性があります。
- Windowsの
os.date制限: Windowsの標準Lua実装では、os.date関数でのタイムゾーン名(%Z)や一部のオフセット形式(%z)の扱いに制限があります。スクリプトはこの制限を回避するためにカスタムのタイムゾーン処理を行っています。