KonomiTV
AGENTS.md1.1k starsChanged 52 days agoMITView on GitHub
Trending
Steady talk.thin dataabout the whole repository
Who's talking about tsukumijima/KonomiTV
- @seloeniseiskoe.bsky.social“GitHub - tsukumijima/KonomiTV: KonomiTV: Kept Organized, Notably Optimized, Modern Interface TV media …”Bluesky · Nov 7, 2025 · 1 likes
- PreMiD/Activities“feat(KonomiTV): add activity”GitHub · Oct 27, 2026
- rokoucha/Mahiron“APIレスポンスに Server ヘッダーが含まれておらず、KonomiTV等の Mirakurun 互換チェックが失敗する”GitHub · Aug 16, 2026
- kazuki0824/recisdb-rs“v1.2.3 (Fix)”GitHub · Mar 5, 2025
- EutropicAI/vs-playground“feat: 支持硬编,qsv nvenc 等”GitHub · Dec 28, 2024
The biggest 5 of 6 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 6
Talked about on GitHub and Bluesky (6 times).
On GitHub · 5
- Oct 27, 2026feat(KonomiTV): add activity — PreMiD/Activities0 reactions · 1 comment
- Aug 16, 2026APIレスポンスに Server ヘッダーが含まれておらず、KonomiTV等の Mirakurun 互換チェックが失敗する — rokoucha/Mahiron0 reactions · 1 comment
- Mar 5, 2025v1.2.3 (Fix) — kazuki0824/recisdb-rs0 reactions
- Dec 28, 2024feat: 支持硬编,qsv nvenc 等 — EutropicAI/vs-playground0 reactions
- Dec 5, 2021feat/channel-logo ① — iamtakagi-lab/daily-annict0 reactions · 3 comments
On Bluesky · 1
- Nov 7, 2025GitHub - tsukumijima/KonomiTV: KonomiTV: Kept Organized, Notably Optimized, Modern Interface TV media server -… — @seloeniseiskoe.bsky.social1 likes and repost
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-new-setting-fieldSkill
- generate-release-notesSkill
- release-checklistSkill
The file
We found no rules to list in this file: it reads as prose or reference rather than instructions.
Files
AGENTS.md
プロジェクト固有の注意事項
- yarn や uv はそれぞれ
client/とserver/のディレクトリに移動した状態で実行してください。ルートディレクトリにはパッケージ管理系のファイルは一切配置していません。 client/package.jsonの mpeg2toh264 Git pin を更新するときは、client/でyarn cache clean mpeg2toh264を実行してから依存関係を再インストールしてください。yarn v1 は Git のコミットが変わっても同じパッケージ名とバージョンのキャッシュを再利用するため、古い JavaScript や型定義が残ります。- サーバー側では uv を使っているので、python コマンドは必ず全て uv run 経由で実行します。python を直接実行すると .venv/ 以下のライブラリがインストールされていないために失敗します。
コミット
- コミットメッセージの接頭辞 (
Update: [Server][Routers/CapturesRouter]など) の形式は、最終的には私個人の感覚で決まっている。原則として、直近のコミットと、変更するファイルの直近のコミットで使われている接頭辞の形式に合わせること。 以下はあくまで原則であり、例外もありうる - クライアントとサーバーの変更は、別々のコミットに分割する。API を追加してクライアントから利用する変更では、先にサーバー側、次にクライアント側の順にコミットする
- 片方の変更がコメントや型の追従程度にとどまる場合に限り、1つのコミットにまとめてよい。その場合も、主な変更がある側に合わせて
[Client]か[Server]のどちらか一方を書く - 範囲表記の
[]は、重ねると親子の階層を表す。[Client][Server]のように、並行する範囲を並べて書かない - サーバーの範囲表記は、
server/app/以下のフォルダ名とファイル名を/で連結し、[Server][Routers/CapturesRouter]・[Server][Models/Program]・[Server][Metadata/CaptureScanTask]のように書く。[Server][CapturesRouter]のようにフォルダ名を省略した形は以前の書き方であり、履歴に残っていても使用しない - DB のマイグレーションを含むコミットの範囲表記は、
[Server][Migrations]ではなく、マイグレーションの対象のテーブルを定義するモデルに合わせて[Server][Models/Capture]のように書く。マイグレーションのファイルだけを変更するコミットも同様とする - クライアントの範囲表記は、
client/src/components/とclient/src/views/以下のファイルであれば、[Client][Captures/CaptureHeader]のようにそのフォルダ名を省略して書く
開発環境構成
サーバー API (port 7000、常にユーザー管理)
- 依頼を受けた時点で、サーバー API は次のいずれかの状態で常駐しています。いずれもユーザーが管理しているプロセスです。リロードモードとリロードなしの開発サーバーは、エージェントが直接起動・停止すべきではありません
- リロードモード:
server/でuv run task devで起動。コード変更が hot reload されます。基本的にこの状態で依頼が来ます - リロードなしの開発サーバー:
server/でuv run task serveで起動。hot reload なしのユーザー権限プロセスです - pm2 常駐:
sudo pm2 start KonomiTVで起動。KonomiTV は root 側の pm2 プロファイルにしかインストールされていないため、pm2コマンドの実行には必ずsudoが必要です。変更を反映するためのsudo pm2 restart KonomiTVは、ユーザーの許可を待たずにエージェントが実行して構いません
- リロードモード:
- FastAPI の listen ポートは常に 7000 で固定です (Akebi HTTPS Server が
127.0.0.77:7010をリバースプロキシしています) - サーバー側コードを変更して挙動を確認したい場合の手順:
- リロードモードで動いている場合は、変更が自動で反映されます
- ただし、DB のマイグレーションは
KonomiTV.pyがプロセスを起動するときに1回だけ適用され、リロードでは適用されません。マイグレーションを含む変更を、リロードモードのサーバーが参照するワーキングツリーへ反映するときは、反映の直後にユーザーへサーバーの再起動を依頼してください (再起動するまでは、新しいモデルが存在しない列を読み書きしてエラーになります)
- ただし、DB のマイグレーションは
- pm2 常駐で動いている場合は、エージェントが
sudo pm2 restart KonomiTVで再起動して反映してください - リロードなし開発サーバーで動いている場合は、ユーザーに「リロードモードでの起動への切り替え、もしくはサーバー再起動」を依頼してください
- リロードモードで動いている場合は、変更が自動で反映されます
- エージェントが直接
python KonomiTV.pyやuv run python KonomiTV.pyを実行するのは禁止です。サーバーの起動には必ず taskipy で定義済みのuv run task serve/uv run task devを使用してください (それでも、上記の通り既存プロセスとの衝突を避けるためエージェント自身が起動することは原則避けてください) - async def で定義された関数で pathlib のうち同期 I/O が発生する関数を絶対に呼び出さないでください。代わりに
anyio.Pathを使ってください - async の処理 (イベントループ) からは、
threading.Lockのような同期ロックを取得しないでください。 ワーカースレッドとイベントループの間で値を共有するときは、イベントループをブロックしない受け渡し方法を選択すべきです (Windows でイベントループ上の同期処理がブロックし、サーバーがフリーズした事故があります) server/data/database.sqliteは利用者が実際に使用している DB なので、検証で値を書き込まないでください。DB に値を書き込んで検証するときは、一時フォルダに DB のコピーを作成して使用してください
クライアント開発サーバー (port 7001、必要ならエージェントが起動可)
- クライアントの開発サーバーは普段は起動していません
- UI を検証する必要がある場合は、
client/でyarn devをエージェントが起動して構いません- 起動すると port 7001 で Akebi HTTPS Server 経由でリッスンされます (内部の Vite は
127.0.0.77:7011でリッスンします)
- 起動すると port 7001 で Akebi HTTPS Server 経由でリッスンされます (内部の Vite は
- 重複起動は禁止です。起動前に必ず
ps -ef | grep viteなどで既存プロセスの有無を確認してください yarn devで起動するクライアントは、開発モード時のみ同じドメインの:7000のサーバー API を直接叩くようハードコードされています (client/src/utils/Utils.ts のUtils.api_base_urlを参照)。Vite の proxy 設定は不要です- UI 検証の URL は、ブラウザが Akebi と同じマシンで動いているときは
https://my.local.konomi.tv:7001です (localhostや127.0.0.1では開けません) my.local.konomi.tvは名前解決した側の127.0.0.1です。ブラウザが SSH クライアント側など別マシンで動くときはmyを使わず、Akebi がリッスンしているマシンの LAN IP をhttps://192-168-1-11.local.konomi.tv:7001の形式 (ドットをハイフン) で開いてください。エディタ設定の変更やポート転送の追加で済ませないでください- 画面を変更した際は、
client/src/styles/mixin.scssに記述されている画面サイズすべて (PC・タブレット横画面/縦画面・スマホ横画面/縦画面/縦画面(iPhone SE サイズ)) をブラウザで開いて確認してください。変更した部品が収まるかだけでなく、その変更により幅が押されたり位置がズレる同じ行の見出しやボタンも確認の対象です。撮ったスクリーンショットは、合否を報告する前にユーザーに表示してください - クライアント開発サーバー経由で API リクエストが想定通りに動かない場合でも、サーバーを立て直そうとしないでください。まず
Utils.api_base_urlの DEV 分岐の挙動を読み直し、port 7000 で動いているサーバー側の状態をps -ef | grep KonomiTVなどで確認してください - 番組タイトルや番組概要を表示するときは必ず
ProgramUtils.decorateProgramInfo(program, 'field_name')を使用してください
ログインが必要な画面の検証 (port 7200、エージェントが起動・停止する)
- お気に入り・タグ・アカウントごとの設定のように、ログインした状態でしか動作しない画面は、ログインしていないブラウザで開いただけで「未確認」と報告せず、検証用のアカウントでログインして最後まで操作してください
server/data/database.sqliteにアカウントやお気に入りを作成すると実際のデータが変わるため、DB の複製を使う検証用のサーバーを port 7200 で別に起動します。yarn devのクライアントは:7000を参照するため、この検証には使えません- 手順は次のとおりです
git worktree add --detach <一時フォルダ> HEADで作業ツリーを作成し、server/.venvと、server/thirdparty/の中の各フォルダへのシンボリックリンクを配置する (server/thirdpartyをフォルダごとリンクすると、作業ツリー側の空のフォルダの中にリンクが入れ子になる)sqlite3 -readonly server/data/database.sqlite ".backup '<作業ツリー>/server/data/database.sqlite'"で DB を複製する (WAL に残っている書き込みも含めて複製するため、ファイルのコピーではなく.backupを使う)config.yamlを作業ツリーにコピーし、server.portを 7200 に、video.recorded_foldersを空の一時フォルダに変更する。Mirakurun を起動していない環境では、general.always_receive_tv_from_mirakurunを false にしないと設定の検査で起動に失敗する- 作業ツリーの
server/でuv run --frozen --no-sync task serveを起動し、https://my.local.konomi.tv:7200を開く。配信されるのは作業ツリーのclient/distなので、クライアントの変更はビルドしてから検証する POST /api/usersで検証用のアカウント (verify/verify-pass) を作成し、ブラウザのログイン画面からログインする。お気に入りやタグは、絞り込みの結果の件数が一意に決まるように API で付けておく
- キャプチャの保存先は実際のフォルダのままなので、検証の中でキャプチャをアップロードしたり、原ファイルを削除したりしないでください (検証用のアカウントは管理者ではないため、原ファイルの削除は拒否されます)
- 検証が済んだら、起動したサーバーを停止し、
git worktree removeで作業ツリーごと削除してください
Docker 版ステージング (port 7100、別物)
/Develop/KonomiTV-Docker以下には別途 Docker 版のステージング環境があります (port 7100、内部 HTTP は127.0.0.77:7110)- 本リポジトリの開発環境とは独立した別プロセスです
HTTPS が必須な理由
- KonomiTV はクリップボードなど Secure Context (HTTPS) でしか動作しない API を使用しています
- localhost 以外でも正規の HTTPS で提供できるよう、Akebi HTTPS Server が
akebi.konomi.tvの keyless server を経由してリバースプロキシを行っています - HTTP に直接アクセスされると Secure Context API が動かず混乱を招くため、内部の HTTP は
127.0.0.77でリッスンする構成になっています
技術スタック
KonomiTV は、クライアント・サーバーアーキテクチャに基づく Web アプリケーション (PWA) です。
以下の2つの主要部分で構成されています。
client/: KonomiTV のフロントエンドアプリケーション (PWA)- TypeScript
- yarn v1
- Vite
- Vue.js 3.x
- Vuetify 3.x
- Pinia
server/: KonomiTV のバックエンド API サーバー- Python 3.13
- uv
- Uvicorn
- FastAPI
- Pydantic v2
- Tortoise ORM
- SQLite (ローカル動作が必要なため MySQL や PostgreSQL は採用できなかった)
- Aerich
KonomiTV が一般的な Web サービスと異なる点は、フロントエンドと API サーバーの両方が各ユーザーの PC 環境で動作する点です。
したがって、Windows と Linux の両方で動作するように開発する必要があります。
Windows では Windows サービス、Linux では pm2 サービスとして動作するよう設計しています。
Python を含むサードパーティーのバイナリはすべて同梱し、利用者のシステムにインストールされたライブラリに依存せず単体で動作すること (スタンドアローン) を重視しています。
同梱のライブラリを OS 側のものへ切り替える変更は、単体で動作し続けるかを検証してから導入してください。
同梱するサードパーティーのバイナリは、Ubuntu 20.04 以降 (glibc を含む) で動作するビルドでなければなりません。
ディレクトリ構成
クライアント (client/)
public/: 直接提供される静的ファイルsrc/: ソースコードviews/: Vue ルートコンポーネント/ページTV/: テレビ視聴関連ページVideos/: 動画関連ページReservations/: 予約関連ページSettings/: アプリケーション設定ページLogin.vue: ログインページRegister.vue: アカウント登録ページMyList.vue: マイリストページWatchedHistory.vue: 視聴履歴ページMyPage.vue: マイページNotFound.vue: 404 エラーページ
components/: Vue コンポーネントWatch/: テレビ・録画番組視聴画面向けコンポーネント群Panel/: 視聴画面右側のパネル内表示用コンポーネント群Twitter/: ツイート検索/タイムライン表示/キャプチャ管理/ツイート表示用コンポーネント群
Settings/: 設定ページから呼び出されるダイアログコンポーネント群HeaderBar.vue: ヘッダーバーSPHeaderBar.vue: スマートフォン用ヘッダーバーNavigation.vue: ナビゲーションBottomNavigation.vue: スマートフォン用下部ナビゲーションSnackbars.vue: 通知メッセージ表示コンポーネントBreadcrumbs.vue: パンくずリスト表示コンポーネント
stores/: 状態管理 (Pinia ストア)services/: サーバー API へのサービスクライアントplayer/: KonomiTV の視聴画面で用いられるライブ/ビデオプレイヤーのロジック (重要)managers/: PlayerController に紐づく様々な機能のロジックを提供し、各機能に責任を持つ PlayerManager 群PlayerController.ts: 動画プレイヤーである DPlayer に関連するロジックを丸ごとラップするクラスで、KonomiTV の再生系ロジックの中核を担う
utils/: ユーティリティ関数とヘルパーworkers/: 重い処理をバックグラウンドで実行するための Web Workers コード (with Comlink)styles/: グローバル CSS の定義 (グローバル CSS はApp.vueの方がメイン)router/: Vue Router 設定plugins/: Vue プラグインの初期化定義App.vue: アプリケーションのルートコンポーネント (グローバル CSS 定義もここに含まれる)main.ts: アプリケーションのエントリーポイント・初期化処理
package.json: Node.js プロジェクト設定と依存関係 (yarn)vite.config.mts: Vite ビルド設定tsconfig.json: TypeScript 設定.eslintrc.json: ESLint コードスタイル設定
サーバー (server/)
app/: FastAPI アプリケーションコードrouters/: API ルートハンドラーChannelsRouter.py: チャンネル関連メタデータ取得 APIProgramsRouter.py: 番組関連メタデータ取得 APIVideosRouter.py: 録画番組メタデータ取得 APISeriesRouter.py: 番組シリーズ関連 APILiveStreamsRouter.py: 放送中テレビ放送のライブストリーミング配信関連 APIVideoStreamsRouter.py: 録画番組のストリーミング配信関連 APIReservationsRouter.py: EDCB と連携したテレビ番組の録画予約関連 APIReservationConditionsRouter.py: EDCB と連携したテレビ番組の自動録画予約条件 (EPG 自動予約) 関連 APIDataBroadcastingRouter.py: データ放送のインターネット接続機能向け APICapturesRouter.py: キャプチャ画像管理 APITwitterRouter.py: Twitter 連携 APINiconicoRouter.py: ニコニコ実況連携 APIUsersRouter.py: ユーザーアカウント管理 APISettingsRouter.py: クライアント・サーバー設定管理 APIMaintenanceRouter.py: サーバーメンテナンス用 APIVersionRouter.py: バージョン情報 API
models/: データベースモデルとスキーマCapture.py: キャプチャ画像とお気に入り・タグなどの関連付けを管理するモデルChannel.py: チャンネル情報を管理するモデル(放送局情報、チャンネル番号、ロゴ、ストリーム設定など)Program.py: 放送番組情報を管理するモデル(番組メタデータ、EPG 番組情報、タイトル、番組詳細、ジャンルなど)RecordedProgram.py: 録画済み番組のメタデータを管理するモデル(EPG 録画番組情報、録画開始/終了時刻など)RecordedVideo.py: 録画済み番組の動画ファイル情報を管理するモデル(ファイルパス、映像/音声コーデック、ファイルサイズなど)Series.py: 番組シリーズ情報を管理するモデル(シリーズ名、シリーズ ID など)SeriesBroadcastPeriod.py: 番組シリーズの放送期間情報を管理するモデルTwitterAccount.py: Twitter アカウント連携情報を管理するモデル(トークン、認証情報など)User.py: ユーザーアカウント情報を管理するモデル(認証情報、権限など)
migrations/: Tortoise ORM のマイグレーションツール: Aerich 向けの DB マイグレーション定義 (Aerich で自動生成されたコードを修正したもの)streams/: テレビ放送のライブストリーミング・録画番組のオンデマンドストリーミング関連の実装LiveEncodingTask.py: ライブストリーミング用のエンコード・ストリーミングタスクを管理VideoEncodingTask.py: 録画番組用のエンコード・ストリーミングタスクを管理LiveStream.py: 放送波のライブストリーミングの状態管理VideoStream.py: 録画番組のオンデマンドストリーミングの状態管理LivePSIDataArchiver.py: 放送波から PSI/SI データを抽出・アーカイブする機能の実装
metadata/: 録画番組データから番組情報などのメタデータを抽出・保存するための実装RecordedScanTask.py: 録画フォルダの監視とメタデータの DB への同期を行うタスクMetadataAnalyzer.py: 録画ファイルのメタデータを解析するクラスTSInfoAnalyzer.py: 録画 TS ファイルや録画データ関連ファイルに含まれる番組情報を解析するクラスThumbnailGenerator.py: プレイヤーのシークバー用タイル画像と、候補区間内で最も良い1枚の代表サムネイルを生成するクラスCMSectionsDetector.py: 録画 TS ファイルに含まれる CM 区間を検出するクラス
utils/: ユーティリティ関数とヘルパーedcb/: EDCB 連携用の API クライアント実装JikkyoClient.py: ニコニコ実況・NX-Jikkyo 連携用の API クライアント実装TwitterGraphQLAPI.py: Twitter API 連携用にリバースエンジニアリングして開発した API クライアント実装TSInformation.py: 日本のテレビ放送で用いられている MPEG2-TS から情報を取得する際に役立つユーティリティ群OAuthCallbackResponse.py: OAuth 認証のコールバック時にブラウザに情報を渡すために返す特殊なレスポンスDriveIOLimiter.py: ドライブごとの同時実行数を制限するためのユーティリティクラスProcessLimiter.py: プロセスごとの同時実行数を制限するためのユーティリティクラス
app.py: FastAPI アプリケーションやルーターの初期化・バックグラウンドタスクの定義config.py: サーバー設定 (config.yaml) のロードとバリデーションconstants.py: サーバー全体で用いられるグローバル定数logging.py: ロギング設定schemas.py: API リクエスト/レスポンス型に用いる Pydantic スキーマ
data/: アプリケーションデータ用ディレクトリdatabase.sqlite: SQLite データベースファイル
logs/: アプリケーションログ用ディレクトリmisc/: メンテナンス・デバッグ用 Pythonスクリプト群static/: サーバー API によって提供される静的ファイル (Git 管理下にあり、放送局ロゴなどが含まれる)thirdparty/: FFmpeg や QSVEncC などのエンコーダーをはじめとした、ビルド済みのサードパーティー実行ファイル (Git 管理外で、uv run task update-thirdpartyで更新する)pyproject.toml: Python プロジェクト設定と依存関係 (uv)uv.lock: uv によって生成される、依存パッケージのバージョンを固定するロックファイルKonomiTV.py: KonomiTV サーバーのエントリーポイントKonomiTV-Service.py: Windows サービス管理スクリプト & Windows サービスのエントリーポイント
設計の基本方針
冗長に設計する失敗と、fail-fast にする失敗を区別する
KonomiTV が扱う失敗には、性質がまったく異なる2種類がある。どちらの失敗かを見極めてから、扱い方を決めること。
- 外部要因による失敗は、冗長に設計して処理を継続する。
- 電波状況が悪く録画の一部が欠損する、TS の途中で映像の PID が変化する、SMB の接続が一瞬切断される、利用者が破損した画像を保存先に配置する、EDCB が応答しない、といった失敗は KonomiTV 側では防げず、毎日どこかで必ず発生する
- 欠損した1枚は黒い画面で埋める、読み込めないファイルはスキップして次へ進む、通信は再試行する、というように、1件の不運で全体を停止させずに、可能な範囲の結果を出力し続ける
- そのうえで、何が起きたかを利用者に分かる言葉でログや画面に残す
- 実装側の誤りによる失敗は、黙って処理を継続せず、即座に明示的に失敗させる (fail-fast)。
- 依存パッケージの互換性のない更新、名前のタイプミス、型の取り違え、同梱すべきファイルの入れ忘れ、設定の読み込み漏れなどは、1度発生すれば同じ条件で毎回必ず発生する
- 1件の不運ではなく仕組みそのものが壊れているため、回避して処理を継続してはならない
見極めの基準は2つある。「同じ入力で再実行しても同じように失敗するか」と、「修正する手段が利用者側にあるか、実装側 (KonomiTV の更新) にあるか」である。
入力や環境によって発生したりしなかったりし、利用者側で対処できるものは冗長に設計する。
どの入力でも必ず発生し、修正に KonomiTV の更新が必要なものは fail-fast にすべき。
なぜ実装側の誤りを黙って継続してはいけないか
- 実装側の誤りを外部要因の失敗と同じように「スキップして継続する」と、壊れていることが誰にも見えなくなる。黙って品質を落としながら動作し続けるのは、停止するよりもはるかに危険な壊れ方である
- 実例: 2026/10/23 に
opencv-python-headlessの上限<5を外したところ OpenCV 5 がインストールされ、cv2.CascadeClassifierが本体から削除された (OpenCV 5 で opencv_contrib の xobjdetect へ移動された)。サムネイルの生成処理では、代表サムネイルの選定を補助する顔検出の例外を大きなexceptが捕捉し、抽出済みのフレームごと破棄していた。さらに失敗を呼び出し元へ伝えず、再解析の API は成功を返して画面に「完了しました」と表示していた。その結果、数日間で85件の録画のサムネイルが生成されないまま、誰も気づかなかった - このとき「顔検出が使えなければ顔なしでスコアを付けて継続する」と修正するのは誤り。サムネイルは生成されるため壊れていることに誰も気づけなくなり、選定の精度が低いサムネイルが静かに増え続け、原因を調査する手がかりも失われる
ベストプラクティス
- 起動時に確認する。 必須の機能が利用可能か (必要なクラスや関数が存在するか、同梱のモデルや設定ファイルを読み込めるか) を、サーバーの起動時か、その機能を初めて使用する前に確認する。利用できなければ、何が不足していてどう修正すればよいかを記載したエラーで停止する。録画1件ごとに同じ失敗を繰り返し、ログに埋もれさせてはならない
- ライブラリが黙って失敗する箇所をチェックする。
cv2.CascadeClassifier(path)のように、存在しないファイルを渡されても例外を送出せずに空のオブジェクトを返す API がある。こうした API の戻り値は、使用する前に必ずチェックし (empty()など)、空ならプログラムの誤りとして例外を送出する - 例外を広く捕捉しない。 外部要因の失敗 (I/O・デコード・通信) を捕捉する
exceptは、捕捉する例外の種類を限定する。AttributeError・ImportError・NameError・TypeErrorのような、プログラムの誤りを示す例外を巻き込まない。外部要因の失敗をまとめて捕捉する必要がある箇所でも、プログラムの誤りは捕捉せずに上位へ伝播させる - 失敗を呼び出し元へ正しく伝える。 処理の失敗をログに記録するだけで、呼び出し元には成功として返す設計にしない。API は失敗したら失敗を返し、画面には「完了しました」ではなく、失敗したことと次に何をすればよいかを表示する
- 補助的な機能でも、原因が実装側の誤りなら停止する。 補助的な機能だからと黙って無効化してよいのは、外部要因でたまたま利用できない場合 (その録画には顔が映っていない、など) だけ
- 依存パッケージは最新版に追従し、メジャーバージョンが上がった際に影響をチェックする。 メジャーバージョンが上がっても、KonomiTV が使用する範囲では互換性に影響しないことが多いため、不要なバージョンの上限は設けずに最新版に追従する
- その代わり、
uv.lock(クライアントはyarn.lock) の更新でメジャーバージョンが上がったパッケージを差分から洗い出し、それぞれの公式の移行ガイドや変更履歴を読んで、使用している機能が残っているかをチェックしてから取り込む - 互換性のない変更が判明し、当面は追従できない場合に限り、理由をコメントに記載して上限を設ける
- その代わり、
そのほかの原則
- ツールや構成を移行するときは、旧方式との互換性を保つための迂回策を恒久的に残さない。すぐに差し替える前提であれば、移行の途中で CI やイメージのビルドが一時的に失敗するのは許容する
- まだ公開していない新しい実装では、途中の版との互換性を保たなくてよい。後から読む人やエージェントが意図を誤解しないコードになっていることを優先する
- 過去のデータ形式の違いは、実際に件数が多いものだけを扱う。ごく短い期間にしか存在せず、数件しかない形式のために、専用の判定処理や移行処理を作成しない
- 1つの処理が複数の出力を生成するときは、一部の出力の失敗によって、生成できたほかの出力まで破棄しない。シークバーのタイル画像を生成できなくても、生成できた代表サムネイルは使用する
- ブラウザのキャッシュを無効化するための値 (サムネイル情報の
revisionなど) は、出力を更新した時点でインクリメントし、単調増加させる - 求められていない要件 (古い版のライブラリとの互換性、正常に動作している処理の作り直し、無いと何が起きるか説明できない防御的な処理) を追加しない。修正の範囲は、問題の解決に必要な最小限にとどめる
慎重に決める設計と、作り直してよい設計
設計にどれだけ慎重になるかは、後から修正するときに手元のコードの変更だけで済むかどうかで決める。
- ほかのものから依存され、利用者の手元に残り続けるものは、先に詳細を詰めて慎重に決める。
- DB のテーブル、API のフィールド・パス・データ構造、ブラウザに保存するデータ (
SettingsStore.tsの設定や IndexedDB) の構造、サーバーと同期する設定の形式がこれに当たる - KonomiTV は配布型のソフトウェアなので、これらを後から変更すると、すべての利用者の環境でマイグレーションを実行することになり、古いクライアントや同期済みの設定との不整合にも対処することになる。本番環境にデプロイしたサービスでも同様で、保存済みのデータのマイグレーションは極力避けたい
- 誤った形式でも動作してしまうため、誤りは見えないまま蓄積し、データが増えるほど修正のコストが上がる
- したがって、本当に必要かを見極めて最小限にし、既存の設計と同じ考え方に統一し、暗黙の前提から外れない形にする。必要性を見極めずに追加した列やフィールドは、使われなくなっても削除にマイグレーションが必要な例外として残る。既存の設計と調和しない形は「ここだけは例外」という知識を増やし、それを知らない人やエージェントが、次の変更で前提に反する実装をする原因になる
- DB のテーブル、API のフィールド・パス・データ構造、ブラウザに保存するデータ (
- 依存される側を持たない画面は、要件を満たしたうえで後から変更してよい。
- 画面を作り直しても影響は画面の中で閉じ、誤りも目に見えるため、表示と動作を確認できれば作り直してよい
- ただし、画面の都合を API やデータ構造に持ち込まない。画面に合わせて API を設計すると、画面を作り直したときに API だけが取り残される
DB のテーブルとマイグレーション
- テーブルとモデルは、既存のテーブルと同じ考え方で設計する。
- Aerich が生成した列の並びと名前をそのまま使用しない (Aerich は外部キーを末尾に、
created_atを途中に出力する) - 書く前に
recorded_videos・recorded_programs・twitter_accountsのモデルを開き、1列ずつ並べて比較する
- Aerich が生成した列の並びと名前をそのまま使用しない (Aerich は外部キーを末尾に、
- 列の並びは、列の意味の流れに合わせる。
id→ 親 (所有者) への外部キー → 本体のデータ → 状態の遷移 (missing_sinceなど) →created_at・updated_atの順にする- ファイルを表すテーブルの本体は、
recorded_videosと同じく、ファイルの同一性 (パス・ハッシュ・サイズ・作成日時・更新日時) → 内容の情報 → 付随するメタデータの順に並べ、メタデータを指す外部キーは関連する列の直後に配置する CREATE TABLEも、外部キーの参照の都合ではなく、親テーブル → 子テーブルの順に書く
- ファイルを表すテーブルの本体は、
- 列名は、既存の同じ種類の列と用語を統一する。省略しても意味が通じる場合でも、
widthではなくimage_widthのように何の値かを明記する (既存のvideo_resolution_widthに合わせる) - 低コストで取得できる値は、現時点で使わなくても保持しておく。
- ファイルの作成日時のように、スキャンのついでに追加の計算・I/O コストなしで取得できる値は、用途が決まっていなくても列として保持しておくべき。後から必要になったときに数十万件を再スキャンするほうが、はるかにコストが高いため
created_at・updated_atを原則として子テーブルにも配置すべきだと考えているのも同じ理由で、デバッグ時にいつ作成され、いつ更新されたかを特定できるようにするために必要- 行を更新せず、作成と削除だけを行うテーブル (お気に入りやタグの付与) は
created_atだけにする
- 対になる値は、コード上でも対で扱う。
file_created_atとfile_modified_atは、RecordedScanTask.pyと同じく、取得・変更の判定・更新を同じ箇所で行う- ファイルの移動のように片方だけが正しく変化する処理に限り、理由をコメントに記載して照合の対象から除外する (Linux ではリネームで ctime が更新される)
- 決まった値だけを取る文字列の列は、モデルでも
cast(TortoiseField[Literal[...]], fields.CharField(...))にする (RecordedVideo.statusと同じ)- 値の一覧はコメントではなく型で表現し、スキーマ・TypedDict・dataclass の同じ値も同じ
Literalに統一する
- 値の一覧はコメントではなく型で表現し、スキーマ・TypedDict・dataclass の同じ値も同じ
- インデックスの列の順序は、列の定義順ではなくクエリで決める。
- 複合インデックスは先頭の列から順にしか使用できないため、等号で絞り込む列 → 並べ替えに使う列 → 同じ値のときの順序を決める
idの順にすべき idを先頭にしたインデックスは主キーと同じ順序で並ぶだけで、絞り込みにも並べ替えにも使用できない- UNIQUE 制約と同じ列のインデックスは、制約が同じインデックスを持つため作成しない
- 列の順序を変更したら、
EXPLAIN QUERY PLANと API の応答時間を確認する
- 複合インデックスは先頭の列から順にしか使用できないため、等号で絞り込む列 → 並べ替えに使う列 → 同じ値のときの順序を決める
- 既存のレコードが持っていない JSON のキーを追加するときは、型を
NotRequiredにして読み込む側で分岐させるのではなく、マイグレーションで既存の行に値を設定して必須のキーにする (サムネイル情報のrevisionと同様に設計する) - マイグレーションを書き直したら、開発用の DB もバックアップを取得してから同じ定義へ移行する。この際、データは可能な限り維持して移行する必要がある。
CREATE TABLEの中のCONSTRAINT "uid_..." UNIQUE (...)の制約名のように、SQLite でテーブルを作り直さないと変更できないものも、適宜テーブルを作り直して統一する
- 新しいマイグレーションの下書きは、
uv run aerich migrate --offline --name <名前>で生成する--offlineは DB を参照せず、直前のマイグレーションファイルの末尾のMODELS_STATEと現在のモデルを比較する。DB に接続する方式では、DB のaerichテーブルに記録されたモデルの状態と比較するため、Tortoise ORM 0.25 の頃に記録された開発用の DB では、モデルを変更していなくてもupdated_atなどの列の変更として扱われて失敗する- 生成されたファイルは、末尾の
MODELS_STATEを残したまま、SQL の部分だけを手で整形する
API の設計
- 管理用のタスク (録画フォルダの一括スキャン・バックグラウンド解析・キャプチャのスキャン) の API は、
/maintenance/<タスク>/runで開始し、/maintenance/<タスク>/statusで進捗 (is_running・processed_count・total_count) を返す。同時に1つしか実行できないタスクがすでに実行中のときは、429 を返す - 管理用の API は外部から利用される前提にないため、きれいな設計にするためにパスを変更してよい
- 複数件をまとめて削除する API は、
POST /captures/deleteのような動詞のパスにせず、コレクションのパスへのDELETE /capturesにする - クエリやフィールドの名前は、実装上のセマンティクスを適切に考慮して命名すべき
- 具体例: 視聴画面でキャプチャを撮影した再生位置を指定するクエリは、実装都合の
capture_positionではなく、既存フィールドと同様の命名であるplayback_positionを使うべき
- 具体例: 視聴画面でキャプチャを撮影した再生位置を指定するクエリは、実装都合の
画面と操作の設計
- 新しい画面は、既存の同じ種類の画面と、ヘッダーの構成・余白・操作の配置を統一する。
- スマホの上部のバーは、ほかのタブと同じ「見出し (またはロゴ) と検索アイコン」の形を維持し、余白はマイリストや視聴履歴に合わせる
- PC の画面をそのままスマホに詰め込んではならない
- 似た用途の定番アプリがある機能では、その操作体系を踏襲する。
- 写真の閲覧なら Google フォトの選択・ボトムシート・左右スワイプなど、利用者がすでに慣れている操作体験に合わせる
- これにより、利用者は新しい操作を覚えずに済み、実装側も長く使われて洗練された設計を活用できる
- 機能を満たすだけでなく、利用者のユースケースから操作を設計する
- 画面の情報は、オブジェクト・ビュー・絞り込みを区別して設計すべき (OOUI)。
- チップは絞り込みにだけ使用し、ビューの切り替えやお気に入りの変更には使用しない
- 絞り込みと並べ替えは同じメニューにまとめる
- 異なる機能や目的を持つ UI コンポーネントを、同一の外観で表示すべきではない
- 同じ種類の要素が並ぶ画面は、どの画面でも同じ操作を実装する。
- キャプチャのタイルが並ぶ画面 (タイムライン・番組別など) では、選択・拡大表示・お気に入り・タグ・ダウンロード・削除のキーボードショートカットをすべて同じ体系で実装する (
components/Captures/CaptureKeyboard.ts) - 一部の画面でだけ操作が動作しないと、ショートカット一覧で案内した操作が押しても何も起きない
- キャプチャのタイルが並ぶ画面 (タイムライン・番組別など) では、選択・拡大表示・お気に入り・タグ・ダウンロード・削除のキーボードショートカットをすべて同じ体系で実装する (
- KonomiTV は PWA としてアプリのように使われるため、アプリ内の画面へ遷移するリンクを新しいタブで開かない。
- 削除のように取り消せない操作は、よく押すボタンの隣に配置しない。
- ︙アイコンのドロップダウンメニューにまとめ、区切り線の下に赤色で配置する (
components/Videos/RecordedProgram.vueのメニューと同じ形) - ただし、削除のほかに項目がないメニューは作らない。確認のダイアログを表示したうえで、操作の並びの右端に赤色のアイコンで直接配置する (
components/Captures/CaptureSelectionBar.vueの複数選択中のバーと同じ形) - ドロップダウンメニューの項目は、使用頻度の高いものほど上に配置すべき
- ︙アイコンのドロップダウンメニューにまとめ、区切り線の下に赤色で配置する (
- 管理者権限やログインが必要な操作も、ボタンやメニューの項目を非表示にせず、グレーアウトもせずに表示する。
- 押したときに、warning のスナックバーで何が必要で次に何をすればよいか (管理者アカウントでログインし直す、など) を伝える (
components/Videos/RecordedProgram.vueの録画の削除と同じ) - キーボードショートカットも同様に、押したときに同じ案内を表示する
- 項目が消えていたり、理由の表示なく押せなかったりすると、利用者はどうすれば使えるのかを判別できない
- 押したときに、warning のスナックバーで何が必要で次に何をすればよいか (管理者アカウントでログインし直す、など) を伝える (
- 画面の文言は、利用者が意味と次に取るべき操作を理解できる言葉で丁寧に書く (UX ライティング)。
- 説明文は、押すボタンにつながるように書く
- 0件のときのプレースホルダー表示は「まだ存在しない」「条件に合わない」「読み込みに失敗した」を区別し、それぞれ次の行動 (条件の解除・再読み込みなど) を示すべき
- 番組情報を表示するときは、取得済みの局ロゴを局名・放送日時と一緒に表示すべき
- 番組の見出しの直下に、局ロゴ・局名・放送時間、番組概要の順に並べ、並べ替えなどの操作はその後に配置する
- PC では縦方向のスペースを使い切らないよう、並べ替えの選択欄を番組概要の横に配置する
- 時間のかかるタスクを開始するボタンは、実行中は無効化し、完了するまで進捗をポーリングして、ボタンの上に件数の進捗バーを表示する
- サーバーの起動時に自動で実行されたタスクの進捗も同様に表示し、ログを見なくても進捗状況と停止したことが分かるようにすべき
- 進捗の文言は「スキャンしています...」のように末尾に ... を付ける
- タップやクリックで動作する要素 (日付の見出しなど) は、誤って文字が選択されないよう
user-select: noneを指定すべき- 番組概要や字幕のように、読んでコピーしたくなる文章だけは選択できるようにする
- 一覧から1階層下の画面には戻るボタンを配置する。結果が0件のときの表示も、通常の表示と同じように作り込んでチェックする
アーキテクチャ上の設計判断と既知の制約
ライブストリーミング (LiveStream / LiveEncodingTask) の協調動作
LiveStream.connect()とLiveEncodingTask.run()は相互依存の関係にある。チャンネル切り替え時はconnect()が旧タスクをcancel()し、CancelledErrorがController()内で捕捉されてクリーンアップに到達するEDCBTuner._isOwner()チェックは二重操作を防ぐガードレールで、handoff()で所有権を移譲した後は旧ストリームからのclose()/disconnect()はこのチェックで弾かれる- Python 3.11 以降では、
CancelledErrorを捕捉して握りつぶせば以降のawaitは正常に動作する (キャンセル要求の回数を示すTask.cancelling()はuncancel()を呼ばない限り減らない)。asyncio.wait()はタスク状態を変更しないが、asyncio.wait_for()はタイムアウト時にタスクを再度 cancel するので挙動が異なる点に注意する - より詳細な処理の流れは
server/app/streams/LiveEncodingTask.py内のコメントを参照すること
録画再生のシーク (VideoStream / VideoEncodingTask)
- 録画再生のシークは
server/app/streams/VideoStream.pyとserver/app/streams/VideoEncodingTask.pyが担当する。関連する実行時ログはライブ視聴と共通のserver/logs/KonomiTV-Server.logに出力され、エンコーダー専用ログは存在しない VideoStream.resolveSegmentSourcePosition()はsegment_mapキャッシュ・TS シーク・MP4 キーフレームテーブルのどの経路でソース位置を解決したかと所要時間を必ずログに出す。この経路の切り分けが録画再生のシーク不具合調査の起点になるため、ログ出力を削らないことVideoEncodingTaskは入力側 TS のキーフレームをTSKeyFrameCollector(server/app/utils/TSKeyFrameSeeker.py) で収集する。エンコーダー出力側のキーフレームはこのキャッシュにおける有効な入力開始位置にはならないsegment_mapキャッシュは録画 ID ごとにバッチ化・直列化されており、ロックはWeakValueDictionary[int, asyncio.Lock]で保持する。これにより、再生中でない録画のロックオブジェクトは自然に解放される- TS キーフレームキャッシュの経路と
TSKeyFrameSeeker.seek()は同じ DTS 座標系 (source_base_dts + playlist_start_seconds) を使うため、両者は直接比較できる - KonomiTV は低遅延と性能を優先する。シークやチャンネル切り替えなど、利用者の操作から配信開始までの経路に、古いエンコードタスクやプロセスの完全な終了を待機する処理を入れない
- 録画再生の
FeedTSStream(PAT/PMT を先頭に付加して tsreadex に送る処理) と、MP4 の psisimux の経路は、過去の不具合修正や外部からのコントリビューションの積み重ねで成り立っており、開発者の手元に検証用のデータが少ない。複雑だからという理由で削除・統合せず、変更するときは段階的に変更する
録画フォルダスキャン (RecordedScanTask) の設計判断
RecordedScanTask.run()は起動時の全件スキャン (runBatchScan()) と新規ファイルの監視 (watchRecordedFolders()) をasyncio.gather()で同時に実行しており、起動時スキャンが完了する前から新規録画の監視は動いているrunBatchScan()はfolder.rglob('*')で見つかった順にファイルを処理する。processRecordedFile()はfile_created_at/file_modified_at/file_sizeが DB の既存レコードと一致すれば重い解析をスキップするため、再スキャンでも変化のないファイルは軽く処理される- 過去に「起動時スキャンで全ファイルを先に収集し
st_ctimeでソートしてから新しい録画を優先処理する」という改善提案があったが、この方式は却下した。全件収集してからソートする実装は、最初の1件を処理し終えるまでに環境依存の固定 IO コストを必ず払うことになり、HDD・NAS・SMB など幅広いストレージ構成でこのコストが無視できない大きさになる。現状の「見つかった順に処理しつつ監視も並行させる」設計の方が、新規録画の反映を遅らせるリスクがなく安全 - Linux の NFS・SMB (CIFS) のマウントでは、別のマシンからの変更が inotify に通知されない。Linux の inotify は自分のマシン内の変更しか検知せず、cifs のドライバーは SMB の CHANGE_NOTIFY を inotify に連携していないため。Windows は SMB 越しでも
ReadDirectoryChangesWが CHANGE_NOTIFY による通知を受け取れる。録画とキャプチャの監視は、Linux でネットワークファイルシステム (DriveIOLimiter.NETWORK_FILESYSTEMS) 上にあるフォルダと、そのサブマウントを含むフォルダだけをポーリングで監視し、それ以外は OS の変更通知で監視する - 見つからなくなった録画は、キャプチャと同じ規則で
Missingにして一覧から非表示にし、1週間経っても復帰しなければ削除する。録画フォルダにアクセスできないときや、録画フォルダに1件もファイルが見えないとき (マウントが間に合わず空のフォルダが見えているときなど) は何も変更せず、新たに見つからなくなった録画が2割を超えるときは削除だけを保留する - 移動やリネームは、サイズ・更新日時 (移動先のファイルシステムの精度の違いを考慮して前後2秒)・ハッシュで照合して同じ行を付け替え、マイリストや視聴履歴が参照する ID を維持する。付け替えるかどうかは、書き込みが完了したファイルを解析する
processRecordedFile()の照合処理だけで判定し、削除イベントの側ではMissingにするだけにする - 同じ内容の録画済みの行があり、その元のファイルがまだ存在するときは、新しい行を作成せずに付け替えを保留し、一覧には元の行だけを表示する。ドライブをまたぐ移動では元のファイルがコピーの完了後に削除される (フォルダごとの移動ではすべてのコピーの完了後に削除される) ため、元のファイルが削除された時点で付け替える。経過時間で移動とコピーを判別すると長時間の移動で ID が失われるため、保留に期限は設けない。元のファイルを読み込めないときや、どの録画フォルダにも属さないときは、元のファイルが存在していても付け替える
- OS の変更通知では、フォルダごとリネームや移動をするとフォルダ自体の通知しか届かないため、フォルダの追加と削除の通知から配下の録画を処理する。それでも削除の通知を取りこぼした場合に備えて、保留中の元のファイルを60秒ごとに確認する
セキュリティの前提
- KonomiTV は自宅の LAN 内での利用を前提としており、インターネットへ公開する場合は利用者が別途認証をかける立場をとる
- データ放送のインターネット接続機能の API が任意のデータを取得できるのは、機能の性質上避けられない
配布 (インストーラー・アップデーター・Docker・CI)
- 「開発版にアップデート」を含め、インストーラーとアップデーターはどの経路でも必ず最新のコードへ更新されるようにする。Docker の構成ファイルへの追記のように、更新に伴って必要になる設定の変更は、利用者に手動で修正させずアップデーターが自動で行う
- README やインストーラーで案内するドライバーの導入手順は、エンコーダーの作者が動作確認済みの構成に合わせ、根拠のある手順だけを記載する。OS 標準のカーネルモジュールで動作するなら差し替えさせず、不要な再起動や根拠のないバージョン固定を記載しない
- CI と Dockerfile で uv の挙動を指定するときは、コマンドの引数があれば引数を使用し、引数がないものだけ環境変数で指定する。Python は setup-python に頼らず uv でインストールする。Git のリビジョンを指定するためだけに
[tool.uv.sources]を使用せず、依存関係の本体に記載する - KonomiTV は利用者の手元で更新される配布型のアプリケーションなので、DB のマイグレーションは配布先で確実に失敗せずに動作しなければならない。Aerich が生成した SQL はそのまま使用せず、必要に応じて手で修正するか手で書く
- 自動生成の SQL は、インデントが崩れていたり、テーブルのコメントや
idx_captures_capture_4c2258のようなハッシュ付きのインデックス名が入っていたりして読みにくい。既存のマイグレーションに合わせて手で整形する - SQL の文字列の中は8文字インデントして揃える。インデックス名は
recorded_programs_start_time_idのようにテーブル名とカラム名 (またはrecorded_programs_time_rangeのような用途を表す名前) で付け、ユニーク制約の名前は先頭にuid_を付ける
- 自動生成の SQL は、インデントが崩れていたり、テーブルのコメントや
エンコーダー・ドライバーのパッチ
- CI で適用する Intel Media Driver・oneVPL・QSVEncC などのパッチや、エンコーダーの引数の変更は、不具合が発生する組み合わせ (特定の GPU 世代と特定のフィルターなど) に厳密に限定して適用する。本来利用できる機能を広く無効化したり、関係のない経路の速度・安定性・画質を低下させたりする変更は入れない。暫定的な回避策より、論理的に説明できる本質的な修正を選択する
.github/workflows/以下で適用するサードパーティーのパッチは、そのまま upstream に提案できる品質で作成する。コメントは英語で最小限にし、KonomiTV などの固有名詞を含めない (コーディング規約の「日本語のコメントを多めに」の対象外)。空白や改行だけの変更など、目的外の差分を混ぜない。パッチは手で編集せず、ソースの変更からgit diffで生成し、適用できることを確認する- エンコードの不具合の検証では、実際の使われ方に沿った組み合わせを必ず含める。インターレース解除は bob と normal の両方を常に検証する。録画の保存用は 1080p〜540p で 24p・30p・60p のすべてを、ライブの HEVC は通信節約モード (480p 程度) を想定する
録画予約のバックエンド (EDCB・Mirakurun)
- 録画予約など EDCB のときだけ利用できる API とポーリングは、Mirakurun をバックエンドにしているときは呼び出さない。判定には
client/src/stores/ServerSettingsStore.tsを使用する。呼び出すべきときに発生したエラーは、APIClientとshowGenericErrorを通して必ず表示し、握りつぶさない - 録画予約の既定値は、EpgTimerSrv に保存された既定の録画設定とプリセットから取得し、クライアントに固定値を書かない。プリセットが既定の1つしかなければ選択欄を表示しない。EpgTimer を使わず、EDCB をバックエンドとしてのみ使う利用者も想定する
- EDCB の実装や挙動は、公式の
xtne6f/EDCBまたはtkntrec/EDCBのソースコード (公式クライアントは EpgTimer) を読んで適宜確認すること。
キャプチャ閲覧 (CaptureScanTask / CapturesRouter)
- キャプチャは1枚あたりのサイズは小さいが十数万〜百万枚に及び、HDD やネットワーク越しのドライブに保存されていることが多い前提で設計する。数十万件の初回スキャンに数時間かかるのは許容し、そのうえで一覧と検索が実用的な速度で動作することを求める
- キャプチャのサムネイルは生成しない。元のファイルが小さいため原画像をそのまま返し、クライアントのキャッシュに任せる (主にローカルから利用するため転送量は重視しない)
- キャプチャの同一性はファイルの内容のハッシュで判定し、フォルダを整理し直してもパスを更新するだけで再解析しない。KonomiTV からアップロードされたキャプチャは、スキャンを待たずに直接 DB に登録し、ハッシュで重複を除外する
- キャプチャに録画番組の ID を保存しない。録画の削除や再スキャンで ID が変わっても紐付けが壊れないよう、番組のキー (network_id・service_id・event_id・開始時刻) を使い、クエリの実行時に紐付ける
- キャプチャは録画と同じく共有フォルダにあるため、ユーザーごとに区別しない (お気に入りとタグはアカウントごと)。原ファイルの削除は、録画と同じく管理者権限を持つユーザーだけに許可する
- 内容のハッシュには SHA-256 を使用する。特別な理由がなければ、広く使われている方式を選択する (このファイルサイズでは、ハッシュ関数による速度の差はほとんど出ない)
- 見つからなくなったファイルの行は
Missingにして1週間後に削除し、同じパスが別の内容で上書きされてどの場所にも存在しなくなったキャプチャも、1週間保持してから削除する。保存先にアクセスできないときや、走査が途中で失敗したときは何も変更しない。保存先に画像が1枚も見えないときや、新たに見つからなくなったファイルが2割を超えるときは、Missingにして一覧から非表示にするだけにとどめ、削除は保留する (割合はすでにMissingの行を除いて計算するため、利用者が大量に削除した場合も次の走査から削除が進む) - 撮影日時は EXIF の値を優先する。EXIF がなく、ファイル名の時刻とファイルの更新日時が大きく離れているときは、コピーによって更新日時が変わった可能性があるため、ファイル名の時刻を優先する
サーバーのテスト (方針)
- 単体テストは、イレギュラーなデータが入りやすい解析処理 (TS・EXIF・番組情報) に限定し、それ以外は E2E テストを基本にする。単体テストで網羅を目指さない
- 解析処理のテストの入力は、実際の録画やキャプチャから作成する。番組情報は変更しない (8単位符号のデコードなど、実データの癖を確認することが目的のため)。数秒の TS は視聴する価値がないためそのまま配置してよく、長い TS は映像を差し替えて、1件あたり数 MB に収める
- テストは開発者の手元の録画フォルダに依存せず、リポジトリだけで誰でも実行できる形にする (将来 CI でも実行するため)
- EDCB は Docker で起動しない (開発機の EDCB-Wine と共存できず、CI でも重いため)。Twitter と Bluesky は実際のアカウントが必要なため、テストしないか簡単なモックにする
- テストは
server/でuv run task testで実行する (スナップショットの更新はuv run task update-snapshots)。単体テストはserver/tests/unit/に、E2E テストはserver/tests/e2e/に配置し、全体が1〜2分以内に完了するようにする - テストの実行中は環境変数
KONOMITV_TEST(pytest-env が設定する) により、DB・設定・サムネイル・ログのファイル名に.testが付き (database.test.sqlite・config.test.yamlなど)、実際に使用しているものと区別される。録画フォルダとキャプチャの保存先には一時フォルダを使用する - E2E テストはサーバーの起動処理ごと実行し、放送のバックエンドには
server/tests/MockMirakurun.pyの偽の Mirakurun を使用する - テスト用のファイルは
server/tests/fixtures/に配置し、元の録画・キャプチャと作成方法を同じ場所のAGENTS.mdに記録する。録画はserver/misc/FixtureTSFileConverter.pyで作成する
把握しているが当面対応しないもの
次の挙動は把握しているが、発生する条件が限られるわりに対応のコストが高いため、当面は対応しない。
レビューで同じ指摘を受けても、発生する条件が広がる新しい事実がない限り修正しない。
- マウントがサーバーの起動より遅れたとき、OS の変更通知で監視している録画フォルダとキャプチャの保存先は、次の一括スキャンかサーバーの再起動まで新しいファイルを検知しない (監視を再設定する仕組みが必要で、検証のコストに見合わない)
- 録画フォルダの中にマウントしたドライブが外れたとき、通知の届き方によっては配下の録画が
Missingになり、次の一括スキャンまで一覧に表示されなくなる (Linux のアンマウントではフォルダの削除の通知は届きにくく、届いてもMissingなので1週間は削除されない) - 録画の付け替えを保留している間に、元の TS をその場で書き換えると (末尾の切り詰めなど)、保留しているコピーは次の一括スキャンまで一覧に表示されない (録画を編集するツールは通常は別のファイルに出力し、発生しても古い内容の複製が一時的に表示されないだけ)
- サーバーの API は、放送時間未定の番組に仮の終了時刻 (Mirakurun では開始時刻 + 5分、EDCB では + 300秒) を設定し、本当の値と区別できない。ライブ視聴中は EIT[p/f] のデコード結果 (未定なら
durationがInfinity) で番組情報が上書きされるため、キャプチャの EXIF には null が書き込まれる。ストリームに接続した直後で、EIT[p/f] を受信する前に撮影したキャプチャだけは仮の値が残る (同じ放送回の後のキャプチャで補完され、区別するには API のデータ構造を変更する必要がある) - E2E テストの中での小さなテスト用ファイルの同期的な読み込みや、アサーションが途中で失敗したときの後処理は、テスト結果に影響しないためそのままにしている (サーバー本体の「async def で同期 I/O を使わない」という規則はテストコードには適用しない)
コーディング規約
全般
- サービス名はコード・型・コメント・UI・文書のすべてで一貫して
Twitterと表記する。XはX Premiumなどの正式な商品名、x.comなどのホスト名、HTTP ヘッダー名のように原表記が技術的に必要な場合だけ使用する - コードをざっくり斜め読みした際の可読性を高めるため、日本語のコメントを多めに記述する
- コードを変更する際、既存のコメントは、変更によりコメント内容がコードの記述と合わなくなった場合を除き、コメント量に関わらずそのまま保持する
- ログメッセージに関しては文字化けを避けるため、必ず英語で記述する
- それ以外のコーディングスタイルは、原則変更箇所周辺のコードスタイルに合わせる
- 不要な薄いラッパーや別名関数は作らず、責務のあるコンポーネントだけを追加する。
- 1か所でしか使わない処理のために、新しいメソッドや例外クラスを作成しない。呼び出し元の中に書くか、名前を付けたい処理のまとまりだけを関数内関数にする
- 新しい定義は、既存の記述順の正しい位置に配置する。 クラスは、クラス定数 →
__init__()→ 生成用のクラスメソッド → 公開メソッド → 内部の補助メソッドの順で、__init__()より前にメソッドを配置しない。スキーマ・ルート・設定・モデルの逆参照のように機能ごとに並ぶものは、末尾に追加せず、app.pyのinclude_routerの順 (チャンネル → 番組 → 録画 → … → 録画予約 → キャプチャ → データ放送 → ニコニコ実況 → Twitter → ユーザー → 設定 → メンテナンス → バージョン) の位置に配置する - 式を1行に詰め込まず、三項演算子を多用しない。条件付きの内包表記や
any()の中の複合条件は、forとifに展開して途中の値に名前を付ける。処理のまとまりごとに空行とコメントを入れる - コメントは、何をするかを肯定形で書き、「〜して、〜ない」「〜させない」のような否定形で締めない。処理のまとまりごとに多めに書くが、名前から分かる値の意味をくどく説明したり、仕組みや計測の経緯を書き連ねたりしない
- 機能名は、利用者が普段使う言葉にする (「ハート」ではなく「お気に入り」)。「orphan」「孤児」の語は、コード・コメント・文書のどこでも使わず、「どの場所にも置かれていない」のように何が起きているかで表現する
config.example.yamlの似た設定 (録画とキャプチャのポーリング間隔など) の説明は、共通する内容を一字一句同じ文で書き、項目ごとに異なる内容だけをその後に続ける- コメントは冗長なくらいでちょうどよい。条件分岐・ループ・例外処理の直前にはその意図を書き、Python では
__init__()で代入するインスタンス変数には「保持する情報」「参照されるメソッド」「前提条件」を必ずコメントとして記す。クラス Docstring には責務のみを記載し、引数説明は__init__()の Docstring に集約する - Enum・Literal・Union 型の文字列表現は
tweet_capture_watermark_position: 'None' | 'TopLeft' | 'TopRight' | 'BottomLeft' | 'BottomRight';のように基本的に UpperCamelCase で命名する必要がある - 通常の Web サービスではないかなり特殊なソフトウェアなので、コンテキストとして分からないことがあれば別途 Readme.md を読むか、私に質問すること
- DB レコードの Pydantic / TypeScript 定義では、親となるレコード本体のスキーマを最上位に配置し、その下に子スキーマをフィールドの定義順に従って並べる
- JSON フィールドの値を生成する際は、辞書リテラル (
{}) を直接書くのではなく、TypedDict のコンストラクタを使用して型構造を明示的に示す - 画像の幅・高さ・総数・間隔など、視覚的に重要な情報を持つフィールドは定義の上部に集約し、重要度の高い順に配置することで一目で把握できるようにする
- 親スキーマから子スキーマへの並び順を徹底し、関連する子スキーマは親となる DB レコードスキーマの直下にまとめて配置する。可読性を損なうような配置変更は行わない
- TypeScript 側のスキーマ定義も Python 側と同じ順序を維持する。もし差分が発生する場合は、その理由をコメントで明記する
Python コード
- コードの編集後には、必ず
uv run task lintコマンドで、Ruff によるコードリンターと Pyright による型チェッカーを実行すること - 文字列にはシングルクォートを用いる (Docstring を除く)
- Python 3.13 の機能を使う (3.12 以下での動作は考慮不要)
- ビルトイン型を使用した Type Hint で実装する (from typing import List, Dict などは避ける)
- Pydantic モデル定義では必ず Annotated 記法を使う。
= Field()型の定義は行わずに全て Annotated 記法で定義すること - 変数・インスタンス変数は snake_case で命名する
- 関数・クラス名は UpperCamelCase で命名する (例:
class VideoEncodingTask:,def GetClientURL():)- FastAPI で定義するエンドポイントの関数名も UpperCamelCase で命名する必要がある
- FastAPI で定義するエンドポイント名は、文法的に比較的正しくなるようパス名や操作を並び替えた上で、「〇〇API」の形で命名すること
- 例: GET
/streams/live/{display_channel_id}/{quality}/mpegts->LiveMPEGTSStreamAPI - 例: PUT
/users/me->UserUpdateAPI
- 例: GET
- クラスに生えたメソッド名は lowerCamelCase で命名する (例:
LiveStream.getONAirLiveStreams()) - 複数行のコレクションには末尾カンマを含める
- 現時点でフォーマッター (Ruff format) は導入していないため、引数の整形は手で行う。関数呼び出しの引数が1行に収まらないとき、またはキーワード引数が3つ以上あるときは、1つずつ縦に並べ、閉じ括弧を独立した行に配置して末尾カンマを付ける
- 生の SQL は
"""で囲み、SELECT・FROM・JOIN・WHERE・ORDER BY・LIMITを句ごとに改行してインデントする (VideosRouter.pyと同じ)。1行に詰めず、'''は使わない - ルーターでは、ルート関数から呼び出す共通の関数を、すべてのルート関数より上に、呼び出される順にまとめる。ルート関数は、パスのルートに近いものから、API ドキュメントを読む人が意味の流れを追える順 (一覧 → 個別の取得 → 作成 → 更新 → 削除、親のリソース → 子のリソース) に並べる
getattr()で型チェッカーを黙らせるのは禁止。参照する属性は型ヒントやプロパティできちんと公開し、どうしてもgetattr()が必要な場合は「その属性が必ず存在する根拠」を詳細にコメントする- すべての Docstring には Args / Returns を明記し、コメントは処理のまとまりごとに必ず加えて「なぜそうするのか」「何を意図した値なのか」を丁寧に説明する。コードを読まなくてもコメントから処理の流れを追えるようにする
- このプロジェクトでは必ずロギングモジュールとして
import loggingの代わりにfrom app import loggingを使うべき - 字幕や番組名などの文章の検索は、録画番組の検索と同じく、空白で区切った語の AND による LIKE の部分一致で行う。日本語は分かち書きの問題があり、フレーズの一部で検索できることが重要なため、SQLite の全文検索は使用しない。速度のために生の SQL を書いてよい (録画番組の検索が生の SQL なのも速度のため)
server/misc/などリポジトリに含めるスクリプトでは、/Develop/のような開発機に固有のパスを参照しない。リポジトリ内のファイルは相対パスで参照し、外部コマンド (tsreplace など) は固定のパスではなく PATH の解決に任せる
Vue / TypeScript コード
- コードの編集後には、必ず
yarn lint; yarn typecheckコマンドで、ESLint によるコードリンターと TypeScript による型チェッカーを実行すること - 入力欄の Enter キーで送信・作成・検索などを行う処理では、IME で入力中の文字を確定する Enter キーを絶対に送信として扱わないこと。必ず
Utils.isIMEComposing(event)(event.isComposingと、macOS の Safari 向けのkeyCode === 229を見る) が true のときは何もしないようにする- 日本語を入力する利用者は、変換を確定するたびに Enter キーを押す。判定がないと、macOS では変換を確定した瞬間にタグの作成や検索が実行されてしまう
- 確定の Enter キーを離したときにも発火する
@keyup.enterは使わず、@keydown.enterで受け取って判定する。@keydown.enter.preventのように修飾子で既定の動作を止めると変換の確定まで妨げることがあるため、送信するときだけ処理の中で止める
window.confirm()/window.alert()などのブラウザ標準ダイアログは絶対に使用しないこと。Vuetify で既存 UI と一貫したダイアログを実装する。標準ダイアログで済ませるのは妥協・甘え・ボケナス実装であり、KonomiTV の UI として許容しない- ダイアログ (v-dialog) は、新しく見た目を考えずに、同じ種類の既存のダイアログを開いて余白・色・ボタンの並びをそのまま合わせること。とくに余白 (マージン・パディング) の一貫性を最優先する
- 確認や入力のダイアログの手本:
components/Videos/RecordedProgram.vueの削除確認、views/Settings/Twitter.vueのアカウント連携。見出しは<v-card-title class="d-flex justify-center pt-6 font-weight-bold">、本文は<v-card-text class="pt-2 pb-0">、ボタンの列は<v-card-actions class="pt-4 px-6 pb-6">に<v-spacer>を配置して右寄せにする - 一覧や設定を扱うダイアログの手本:
components/Settings/CommentMuteSettings.vue。見出しは左にアイコン・右に閉じるボタン (fluent:dismiss-12-filled) を配置し、本文はpx-5 pb-6、スマホの縦画面では左右の余白を 12px に詰める - 複数の操作から1つを選択させるダイアログの手本:
views/Settings/Account.vueの設定の同期の競合のダイアログ。利用者に二択を選択させるときは、スイッチをオンにしてからダイアログを表示する形にせず、操作ボタンを縦に並べて選択させ、キャンセルボタンも配置する。改行が自然な位置に来るよう幅を調整する - ダイアログの実行ボタンとチェックの色は
secondaryを使用し、削除など取り消せない操作のボタンだけerrorにする。ボタンにprimaryは使用しない。入力欄 (v-text-field) のフォーカスの色は、既存のダイアログと同じくprimaryのままにする - ダイアログのボタンには、キャンセルを含めて必ずアイコンを付ける。キャンセルは
color="text" variant="text"にfluent:dismiss-16-filled、実行ボタンはvariant="flat" height="40" class="px-3"に操作を表すアイコン (削除ならfluent:delete-16-regular) を、<Icon width="18px" height="18px" />と<span class="ml-1">の組で配置する - 入力欄は
variant="outlined"で枠を付ける。同じダイアログの中に枠のある入力欄と枠のない入力欄を混在させない - ボタンの文言は、何が起きるかを短い動詞句で書く (「キャプチャを削除」「名前を変更」「追加」)。「作成して付ける」のように操作を2つ並べた文言や、「削除する」「OK」のような何が起きるか分からない文言は使用しない
- 項目数が少ない一覧 (タグなど) のダイアログに、絞り込みの入力欄を配置しない。配置する場合は、同じものの一覧画面にも同じ絞り込みがあることをチェックする
- 確認や入力のダイアログの手本:
- 文字列にはシングルクォートを用いる
- 新規で実装する箇所に関しては Vue 3 Composition API パターンに従う
- Vue.js 2 から移行した関係で Options API で書かれているコンポーネントがあるが、それらは Options API のまま維持する
- 新規で実装する Vue 3 Composition API のコンポーネントでは、原則として変数を lowerCamelCase で命名する
- FastAPI サーバーでは snake_case で命名している関係で外部 API のフィールドは全てスネークケースになっているが、これはそのまま参照して良い
- TypeScript による型安全性を確保する
- API の応答を待つ操作 (お気に入り・タグ・削除・次の項目への移動など) は、押した時点の対象を変数に保持しておき、応答が返ったときにまだ同じ対象を表示している場合だけ画面に反映する
- 応答を待つ間に、利用者はダイアログを閉じたり別の対象へ移動したりできるため、応答時点の
propsや選択状態を対象として扱うと、別の対象に結果を反映してしまう
- 応答を待つ間に、利用者はダイアログを閉じたり別の対象へ移動したりできるため、応答時点の
- 取得に失敗したことを、0件や「存在しない」と同じ値で表現しない
- 一覧の取得は失敗を
null、0件を空の配列で返し、呼び出し側は?? []のように空の配列へ置き換えずに、読み込めなかったことを表示する - 1件を返す取得で
nullがすでに「存在しない」を表すときは、失敗をundefinedなどの別の値で返し、失敗した結果を保持し続けずに再読み込みできるようにする
- 一覧の取得は失敗を
- コンポーネント属性は可能な限り1行に記述 (約100文字まで)
- 必ず day.js を utils/index.ts からインポートして使うこと!!!new Date() を絶対に使うな!!!
- EDCB もサーバーも日本時間を基準に動作するため、クライアントの表示や日付の計算も、ブラウザのタイムゾーンに関わらず常に日本時間 (Asia/Tokyo) で行う (utils/index.ts の day.js はそのように設定されている)
- ユーザー設定の正本はクライアントが保持し、サーバーはデバイス間で同期するための保管場所に徹する。これにより、ログインしなくても動作し、サーバーが一時的に停止しても設定が失われない。リプライの連投先のような一時的な状態も、サーバーのメモリではなくクライアントで保持する。設定のインポートでは、DB の連番 ID に依存する値を別のサーバーへ持ち込むかを選択できるようにする
- クライアント側で新たに永続化したい値が出てきた場合、
localStorage.setItem/getItemを直接呼ばず、必ずclient/src/stores/SettingsStore.tsのILocalClientSettings/ILocalClientSettingsDefaultに集約する。SettingsStore は LocalStorage への永続化と、KonomiTV アカウントによるサーバー側設定との双方向同期を一手に引き受けており、独自キーを直書きするとこの同期の枠組みから外れてしまう- DB の連番 ID に依存する値 (
selected_twitter_panel_accountなど) は環境が変わると意味を失うため、ENVIRONMENT_SPECIFIC_SETTINGS_KEYSに加えて同期無効にする - 他者の実装をレビューする際は
localStorage/sessionStorageを grep し、この集約を迂回した直接アクセスが紛れ込んでいないか必ず確認する - なお、アクセストークン (
Utils.ts)・データ放送 NVRAM エミュレーション (DataBroadcasting.vue)・DPlayer 側のキー (Jikkyo.vueのdplayer-danmaku-*) は、ユーザー設定ではなく認証状態・ハードウェアエミュレーション・サードパーティ側の永続化キーであるため、この集約ルールの対象外として既存のまま残っている
- DB の連番 ID に依存する値 (
CSS / SCSS スタイリング
- このプロジェクトで使用している色 (CSS 変数) などは
client/src/App.vueやclient/src/plugins/vuetify.tsに定義しているので、それを参照すること - 新規に UI を実装する際は、すでに実装されている他のコンポーネントやページの大まかなデザインの方向性を踏襲すること
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

