FR: recorded files API

[kounoike]

（性懲りもなくまた）mirakcのフロントエンドになる録画管理アプリを作ろうとしているのですが、
録画されたTSファイルにアクセスするときにmirakcの設定やdockerのボリュームマウントなど色々と複雑になって頭を悩ませていました。

https://github.com/mirakc/mirakc/blob/main/docs/web-api.md#web-api-endpoints-for-recording ではListing/Getting metadata/Streamingの3つのAPIはout of scopeとなっていますが、この3つのAPI＋削除（schedule.jsonからの削除＆ファイルシステムからの削除）の機能を実装することは出来ないでしょうか？

以前タイムシフト機能を使って全録システムを構築したときは番組終了のイベントを拾って https://github.com/mirakc/mirakc/blob/main/docs/web-api.md#get-apitimeshiftrecorderrecordsrecordstream でTSファイルを取得して処理することで、mirakcとクライアント側の独立性を保ててシステムを構築しやすかったです。
同じ開発体験を通常の録画時にもしたいため、この機能の実装を検討していただけると助かります。

[masnagam]

少し考えてみたいと思います．

以下の記述は決してmirakcにapiを追加することを拒否しているわけではありません．
どのようにするのがよいのか考えるための話し合いだと捉えてください．

現状，私自身は

• mirakc
• recman
• redis (トランスコードのためのキュー)

のように複数のサーバーを動かしています．recmanはrecording/simple-rules.jsを改造したものとなっており，

client.on('recording.stopped', async (schedule) => {
  console.info(`Recording stopped: ${schedule.program.id}: ${schedule.program.name}: ${schedule.state}`);
  // update metadata
  await Deno.writeTextFile(
    `/recording/${schedule.options.contentPath}.json`,
    JSON.stringify(schedule));
  if (schedule.state === 'finished') {
    const job = await addTranscodeJob(client, transcodeQueue, schedule);
    console.info(`Recording stopped: ${schedule.program.id}: ${schedule.program.name}: transcode#${job.id}`);
  }
});

のような感じで録画終了後の処理をしています．mirakcを直接改造しなくても，別サーバーに必要なエンドポイントを追加すれば，恐らく欲しい機能は実装できるのではないかと思います．

ただ，この場合はサーバーを２つ動かすことになりますし，mirakcのマウント機能を使ってフロントエンドを動かす場合，same originの制限をいくらか緩和しないといけないだろうとは思います．そう考えると，mirakcにapiを追加することには十分利点があると思われます．

mirakcにapiを追加した場合，恐らく以下のような要望が自然と発生すると想像します．

• 録画データの検索機能
  • 録画数が少ない場合はフロントエンドで処理できますが，多くなってくるとjsで処理するのは難しくなるだろうと思われます（数千件とかでも今のpcなら処理できるかも？）
• 空き容量が少なくなったら古い録画を自動削除
  • 録画中に容量が足りなくなる可能性があるため，これをフロントエンドで実装するのは多分簡単ではないです
• その他，一般的なレコーダーに備わっている機能を追加してほしいという要望

これらはごく自然な要望ですし（私は必要としていませんが），実装するべきなのでしょうが，すべてをmirakcに追加していった場合，メンテできるか少し不安があります．追加するにしても，オーナー制などを導入して機能を実装した人たちだけでメンテしていけるような仕組みを作ってから追加しないと，後で面倒なことになるのではないかと少し心配です．

schedule.jsonからの削除

録画済みの情報は一時的なもので，録画後１５時間が経過すると自動で削除されます．これはある種のログみたいなもの（録画完了通知みたいなもの）なので，消さなくても大丈夫ではないかと思います．

[kounoike]

その場合、mirakcをどういう風に設定（docker composeでどうボリュームマウントしたか、recording.basedirがどうなってるか、録画予約時にどういうファイル名に設定したか（これは今回はそのサーバ側で把握できますが））を把握していないとならず、システム間の結合度が非常に高い状態になっている、と考えています
HTTP APIで録画ファイルの取得・削除が出来るとmirakcがファイルシステムをどう扱っているかに関与せずにシステムが作れる上、ファイルシステムを共有していない状態（例えば録画は自宅だがエンコードをクラウドでするとか）でも良くなりシステム構成の柔軟性が上がります

[masnagam]

なるほど，理解しました．

提案されたapiの追加自体は多分それほど難しくないのではないかと思います．
録画済み一覧のための情報を新たに保存しないといけませんが，他と同様にjsonファイルで保存するのが簡単でしょう．

削除時に通知する新しいイベントなどを追加したほうがよいかもしれませんが，これもそれほど難しくはないでしょう．

少し考えてみます．

[kounoike]

削除には

• 管理から外す（JSONから消す）だけ
• 実際にファイルも消す
  の2通りがあると良さそうですね

録画済み一覧の保存については今まで通りのschedule.jsonだけにして、設定ファイルに「何時間後に消す」or「消さないようにする」の設定を付けるのでも良いかもしれません

後は、JSONが巨大になるとたまたま保存のタイミングで強制終了とかあると不安ですので、SQLiteあたりの導入も考えた方が良いかもしれませんね。まあ、とりあえずはJSONで良いと思います

[masnagam]

ああそうか，特定のフォルダーにファイルが入っているんだから，それをlsすればいいだけか．
メタ情報はtsから再度取り出すこともできるけど，念の為，別ファイルに書き出せば，一覧を管理するファイルやデータベースを別途用意しなくても良さそうです．

もっと簡単に実装できそうな気がしてきました．

[masnagam]

強制終了がsigtermであれば，録画途中のものはどうにもなりませんが，完了後のメタデータ保存とかなら，それが完了するまで待てると思います．
sigkillとかが来たら，それは送ったほうが悪いので救済不能ですが．

[kounoike]

録画データの検索機能

確かにあるといいなとは思いましたが、検索の実現には色々あるのでmirakc自体が提供する必要はないかなと思いました
単純な部分一致、正規表現、あいまい検索、embeddingによるスマート検索、EPG/ARIB字幕/文字起こしからの内容での検索、などなど色々考えられますが、それはmirakcの外側で提供することかなと思いますし、そういう管理アプリを作ろうと思っています

空き容量が少なくなったら古い録画を自動削除

これも分かるのですが、最低限にして空き容量の取得だけが出来るようになれば、クライアント側で監視して必要に応じて削除処理をしていけば良いのかなと思います（そのためにも削除APIが欲しい）

15時間が経過すると自動で削除

あれ、そうなんでしたっけ・・・
そうなると一覧の元になるデータがなくて困ったことになりますね・・・
もしかすると提案したAPI実装するとしたら、ここが一番大事な変更点になるかもしれないです

[kounoike]

私がやろうとしていることは今のところ録画が終わったら即座にmirakcからファイルを回収して別の場所で管理するようにしようかと考えていますが、mirakc自体の機能として録画済みファイルの一覧機能を提供する場合には以前に録画したファイルをすべて覚えていないとならず大変かなと思いました

[kounoike]

（本筋から脱線してますが）

サーバー側で実際の検索処理などを行うことになります

最近文字起こしやドキュメント検索などの技術の進歩が活発なので、その成果を取り入れて大量の録画の中から欲しい情報を見つけやすく出来ると面白いかな、と考えています
例えばmeilisearchにEPGから得た情報、ARIB字幕や文字起こし結果などを入れておくだけでも面白そうかな、と

[masnagam]

今なら自然言語で検索とかするのが良いのでしょうね．
and/or条件とかやり始めると面倒ですし，google検索とかで機能は提供されてますが，自分なんかほぼキーワードの羅列でしか検索してません．
自分が特別だとは思わないので，多分多くの人がand/orなどの機能は使ってないでしょうね．

以前に録画したファイルをすべて覚えていないとならず大変かなと思いました

数が多くなるとjsonでは難しくなってきますね．データベースを使いたいところですが，導入するべきか少し悩みます．
メタデータを別ファイルにすれば，録画一覧を保存するjsonのサイズは小さくなるので，とりあえずこの方法で何とかなるかというところですね．
無理そうならデータベースを素直に導入することになると思います．

[kounoike]

and/or条件の検索式の標準化をして欲しいです・・・
システムごとに違ってて検索の仕方が分からないので

個人的にはmirakcは単体で動いていて欲しいのでDB導入するならsqlite推しです・・・

[kounoike]

多分真面目にテーブル定義しないで、

• id
• json_str
  の2カラムだけのテーブルで十分そうな気がします

[masnagam]

スレッドが別れてしまったので，新たに作成します．

削除には

ファイルを１つ削除するのも２つ削除するのも同じことなので，対応は難しくないと思います．

録画用フォルダーにはmirakcが作成するファイル以外を入れないことを前提条件として，録画一覧jsonやデータベースを導入しない実装をまずは考えてみようと思います．

[kounoike]

ああそうか，特定のフォルダーにファイルが入っているんだから，それをlsすればいいだけか．

contentPathでディレクトリ掘ってることもありますよ・・・？

クソデカschedule.jsonになることを避けるなら、schedules/XXXXX.json, YYYYYY.jsonって感じでprogram_id辺りで採番したファイル名にため込むとかもアリなように思いました

[kounoike]

（番組タイトルからファイル名付けてたら勝手にディレクトリ掘られてました🤣）

[masnagam]

そうですね，パスは自由に指定できます．
しかし，それはあくまでPOSTに指定したoptions.contentPathが原因なので，指定しない限りはそうはなりません．

options.contentPathに制限を追加するか，一覧するファイルの拡張子をconfig.ymlなどで指定させれば，それを元にファイルを集めることが可能だと思います．

[masnagam]

#2056 を追加しました．

[kounoike]

フォルダ掘る機能を、例えば YYYY/YYYY-mm-dd/番組タイトル.ts にしてる人とかもいると思うので、制限追加はちょっと・・・
あとファイルパスをリクエストに含めるのもなんか気持ち悪い（言語化出来てなくてすみません）ですね

👆の特定ディレクトリに {id}.json 作っていくのはどうですか？
例えば GET recording/records/{id}/stream のときもJSON見に行く→contentPathが分かる→ファイルが読めるし、GET recording/records はそのディレクトリ以下のJSON全部読んで繋いで返すだけなので・・・

[kounoike]

（ここまでやってきて言うのもなんですが）
スレッドリプライはあまり使わないようにして、縦に伸ばしていった方が逆に読みやすいかもしれないですね

[masnagam]

同意します

[kounoike]

それをリプライで言いますか？（笑）

[masnagam]

例えば YYYY/YYYY-mm-dd/番組タイトル.ts にしてる人とかもいると思うので

この場合でも，*.tsを収集対象とすれば行けるのではないかと思います．

あとファイルパスをリクエストに含めるのもなんか気持ち悪い

なるほど，idを使う場合，idとパスのマッピングが必要になり，結局管理ファイルが必要になるのか．
当初これらのapiを追加しないつもりだったので，options.contentPathを追加して好きな名前を作れるようにしたのですが，面倒なことになりましたね．

👆の特定ディレクトリに {id}.json 作っていくのはどうですか？

これはいいアイディアです．{id}.jsonにメタデータも入れておけば，ファイルの数も２つのままで増えませんし．

[masnagam]

メタデータには録画予約情報も入っているから，当然パスも入ってますね．

[kounoike]

メタデータには録画予約情報も入っているから，当然パスも入ってますね．

はい。ほぼschedule.jsonに入ってるうちの1レコードがファイルに切り出されたもの、というイメージでした
GETでそれがそのまま返ってくれば十分かなと思います

[masnagam]

{id}.jsonは別途管理用のフォルダーを作って，そっちに保存します．

録画ファイルを手動で消されたりすると内部矛盾が発生しますが，まあ何とかなるでしょう．

[masnagam]

実際の作業は作業ブランチで行います．

PRを作成するので問題ないかコードレビューをお願いしたいです．
rustのコードはよくわからないという場合には，apiのみの確認だけでも十分です．

[kounoike]

{id}.json は別途管理用のフォルダーを作って，そっちに保存します．

そうですね。jsonがあって.tsが無いときには404か500とかで返る感じでしょうか
そういう「tsがあってjsonが無いときにそのjsonを消す」機能もあればベターでしょうけど、無くてもまあ・・・？
DELETE recording/records/{id} のときにエラーにならずにjsonだけを消せればとりあえずは良いと思います！

[masnagam]

DELETE recording/records/{id} のときにエラーにならずにjsonだけを消せればとりあえずは良いと思います！

確かに，それだけでいけるかもしれませんね．

[masnagam]

今日はもうこれ以上返信しませんが，なにかあればいつでもここにコメントを書いてください．

[kounoike]

DELETE recording/records/{id} のときにエラーにならずにjsonだけを消せればとりあえずは良いと思います！

確かに，それだけでいけるかもしれませんね．

GET系の何かで「あ、jsonがあってtsが無い状態だな」って分かるようなレスポンスになってるとやりやすいですね
HEAD recording/records/{id}/stream でtsの有無が確認出来るとか

今日はもうこれ以上返信しませんが，なにかあればいつでもここにコメントを書いてください．

リアルタイムでレスが返ってきたので助かりました！ありがとうございました！

[kounoike]

👆があると一覧取得してjson/tsの対応取れてるか全部チェックして対応してないのは消していく
みたいなツールをクライアント側で書けますね、という話です

[masnagam]

GET系の何かで「あ、jsonがあってtsが無い状態だな」って分かるようなレスポンスになってるとやりやすいですね

GET recording/records/{id}で返すモデルにsizeを追加します．ファイルがないとnullになります．

HEAD recording/records/{id}/stream でtsの有無が確認出来るとか

stream系のエンドポイントはすべてGET/HEADを実装しているので，HEAD recording/records/{id}/streamも追加します．

[masnagam]

とりあえずapiだけ追加しました．
https://github.com/mirakc/mirakc/tree/feat-recording-endpoints

実装はダミーなのでそのまま使うことはできません．
多分stub（mock）を書いてテストをすると思うので，その参考にしてください．

足りない機能があれば，ここでコメントしてください．

[masnagam]

ブランチをcheckoutしてビルドして動かせば，localhost:40772/api/debugからもドキュメントが読めます．
ただ，上で書いたようにダミー実装なので，swagger uiからのapi呼び出しは機能しません．

[kounoike]

ありがとうございます！
まだ動かしてないですが、エンドポイントとしては良さそうに思います

録画終了前にstreamにアクセスしたときの挙動が気になりました
欲を言えば録画終了前にstream読むと、録画済みの部分は一気に来た上で残りは受信するごとに徐々に送られてくる、みたいなことが出来ると放送中に直でオブジェクトストレージに突っ込んだり、リアルタイムでエンコードして行ったりということも出来るかな、と思いました
・・・が、まあとりあえずはシンプルに録画終了後からしか読めない、でも良いと思います

[masnagam]

欲を言えば録画終了前にstream読むと、録画済みの部分は一気に来た上で残りは受信するごとに徐々に送られてくる

最終的には録画開始時にrecordを作成するので，録画中のデータを読み出すことも可能になります．
ただ，録画データファイルのEOFに達するとfile readerは閉じてしまうので，その時点でhttp chunk responseは終了してしまうのではないかと推測します．

現状，単純にファイルをopenしてreadしていますが，tail -c +0 -fでファイルを読み出せば所望の動作にできるとは思います．この場合，自然とEOFにはならないので，録画終了時にhttp chunk responseを終了させる必要があります．

[masnagam]

どうもrange requestsが謎実装になっていることがわかったので，しばらくの間は使わないでください．チケットを作ってあるので後で修正します．

[masnagam]

データベースなしでrecord idがユニークであることを保証するのは面倒なので，record idの型を数値から文字列に変更しようと思います．
同じ番組を同時に複数録画することはできない仕様になっているので，program.idとtimestampからrecord id文字列を作ることにします．
多分固定長の文字列になると思います．

[masnagam]

タイミングなどの問題から，recordの作成・更新・削除のイベントを別途追加します．
recording.startedの時点ではrecordに安全にはアクセスできません．
recordへのアクセスはrecord作成通知後に行う必要があります．

[masnagam]

@kounoike 実験に使えるレベルまで実装が完了しました．ドキュメントやテストを追加することはあると思いますが，不具合がない限りapiが変わることはないと思います．

差分確認用に PR #2073 を作成してありますが，まだ作業は完了していません．完了したらapiなどの確認のためレビュー依頼を出します．

[masnagam]

PRでのチェックが失敗していますが，ローカルではテストはすべてパスしています．
多分，環境の違いが原因だと思います．

[masnagam]

@kounoike githubでreviewerに設定するためにはメンバーとしてどこかに追加しないといけないみたいなので，とりあえずreadでmirakc/mirakcに追加してみました．この機能を使ったことがないのでわからないのですが，もしかするとteam設定とかをいじらないと無理かもしれません．あまりにも面倒な場合にはgithubの機能を使うのを諦めることにします．

[kounoike]

invite受けておきました
レビューコメントも出来てるようです
（意図せずパーミッションが空きすぎていて、何か変なところに書けたりしないかとかは未確認です）

[kounoike]

まだ本格的に使い始めていないですが、ちょっと試したところ、「contentPathに興味がない（実体が何て名前のファイルでも良い）のに、必須項目で面倒くさい」と感じました。
contentPathを省略した場合はmirakc側が勝手に名前つけてくれると嬉しいな、と思います。
まあ、機械的に.tsとかにすれば良いのでそこまで優先度高い話ではないですが、一応お伝えしておきます。

[masnagam]

機械的に.tsとかにすれば良いのでそこまで優先度高い話ではないですが、一応お伝えしておきます。

mirakcはもともと録画ファイルを隠さず，ユーザーが直接ファイルにアクセスすることを想定したapiだったという理由からconentPathが必須となっていました．
/api/records利用時は直接録画ファイルに触れる機会が減るので，optionalに変更しても良さそうですね．
recordファイル名と同じにすれば良いと思うので，optionalに変更しましょう．

[masnagam]

/api/records無効化時はこれまで通りcontentPathは必須とします．

[masnagam]

90aba21 で実装しました．

Record.options.contantPathではなく，Record.contentPathを使ってください．
Record.options.contantPathは録画時に指定した値なので，contentPathを指定しなかった場合，undefinedとなります．

[kounoike]

ええと、ちょっと分からなかったのですが、

• POSTするときにoptions.contentPathを指定しなかった場合
  　　- Record.options.contentPathは空
  　　- Record.contentPathはmirakcが自動で決めたファイルパスが入っている
• POSTするときにoptions.contentPathを指定した場合
  　　- Record.options.contentPath、Record.contentPathともに指定した値が入っている

という認識で大丈夫でしょうか？

[masnagam]

概ねあっていますが，以下に正確に書きます．

• POSTするときにoptions.contentPathがundefined（つまりcontentPathのプロパティ自体設定しなかった）の場合
  • Record.options.contentPathはundefined
  • Record.contentPathはmirakcが自動で決めた相対ファイルパスが入っている
• POSTするときにoptions.contentPathがnullの場合（これを指定することは稀だと思いますが）
  • Record.options.contentPathはnull
  • Record.contentPathはmirakcが自動で決めた相対ファイルパスが入っている
• POSTするときにoptions.contentPathを指定した場合
  • Record.options.contentPathは指定した値
  • Record.contentPathは..などを解決した相対ファイルパス

Record.options.contentPathを書き換えてしまうと，ドキュメントの説明が少し面倒なことになるので，Record.contentPathを追加しました．
Record.optionsはRecordingOptions型なのですが，その説明が埋め込み先依存で変わってしまうためです．

config.recording.records-dirが指定されていない場合は，options.contentPathはこれまで通り必須項目になります．

[masnagam]

8f97c45 にてrecording.record-savedイベントにrecordingStatusを追加しました．
recordingStatusを確認するだけの目的でGET /api/records/{id}を呼び出す必要はなくなります．

[masnagam]

今更で申し訳ないのですが，recordの構造を以下のように変更しようと思います．

{
  "id": ".."
  "program": { .. },
  "service": { .. },
  "tags": [ .. ]
  "recording": {
    "options": /* record.options から移動 */,
    "status": /* record.recordingStatus から移動 */,
    "startTime": /* record.recordingStartTime から移動 */,
    "endTime": /* record.recordingEndTime から移動 */,
    "duration": /* record.recordingDuration から移動 */
  },
  "content": {
    "path": /* record.contentPath から移動 */,
    "type": /* record.contentType から移動 */,
    "length": /* record.contentLength から移動 */
  }
}

[masnagam]

675016e で移動しました

[masnagam]

実装は終わりました．
不具合や要望がなければこれ以上修正することはありません．
確認が終わったらPRを承認してください．

[kounoike]

/events で、epg.programs-updated は接続時に全チャンネル分流れてきますが、同じように recording.record-saved も全録画の分流すというのはどうでしょうか？
前者は多分起動の順番などで受け取れなかったときの救済処置だと思うのですが、後者でも同様に受け取れなかったときのリカバーがあったら良いかなと思っての提案です。
クライアント側の実装面でも録画が終わるときしか流れてこないと動作確認が辛いというのもあります。

[kounoike]

まあ、record全部流すのはだいぶ重いかもしれないので悩ましいところですけど・・・

[masnagam]

egp.programs-updatedと同様にするならasyncを使うのでそれほど負荷は大きくない気がしますが，数が問題ですね．．

mirakc/mirakc-core/src/epg/mod.rs

Line 760 in ec039c4

// Create a task to send messages.

egp.programs-updatedはチャンネル数程度なので上限はないものの，現状（また将来も）多くとも100以下でしょうが，recording.record-savedは数千となる可能性があります．

実際の動作を確認したところ，１つのイベント送信は1ms以下でした（MeLE Quieter 3C 有線接続）．
つまり，1000程度であれば1s以下ですべてのイベントが送受信されます．
ホップ数が多くなるともう少し時間がかかるかもしれませんが，イントラネット以外での運用は禁止なので，ホップ数の多いケースは無視してよいだろうと考えます．

もともとイベントは大量に送っても良いように，idのみ送るなどデータ量を絞ってあります．
多分/events接続時にrecording.record-savedを全録画の分送っても大丈夫でしょう．

[kounoike]

設定でオン・オフ出来ると良いかもしれないですね

[masnagam]

f06a225 で対応しました．

オン・オフは実際に問題となったときに追加することにします．

[kounoike]

そうですね、この機能を使う人が他にどれだけいるのかという状態ですから今はオンだけで良いと思います
確認したらApproveしておきます