Merge pull request #21 from kounoike:documentation/add-README

README、docker-composeのサンプルの追加

README.md

@@ -1,4 +1,134 @@
 # dtv-discord-go
 
-Discordを使った[mirakc](https://github.com/mirakc/mirakc)による録画管理ツール
+Discord の Bot として動作する [mirakc](https://github.com/mirakc/mirakc) による録画管理ツールです。以下の機能を持っています。
+
+- 番組情報の自動投稿機能
+- 投稿へのリアクションで予約する機能
+- フォーラムへのスレッド作成で自動的に番組検索をし続ける機能
+- 自動検索時にメンションを付ける通知機能
+- 自動検索時に録画を行う自動録画機能
+
+## セットアップ
+
+### Discord Application の登録と Bot tokenの取得
+
+1. https://discord.com/developers/applications をブラウザで開きます（Discord アカウントで認証が必要です）
+2. 右上の New Application ボタンを押します
+3. CREATE AN APPLICATION のモーダルで NAME に好きな名前を入れます
+4. 規約を読み、チェックボックスにチェックを入れます
+5. Create を押します
+6. 必要に応じてNAME、APP ICON、DESCRIPTIONを書き換えます
+7. 左のメニューの Bot を選択し、Add Bot ボタンを押します
+8. Yes, do it! ボタンを押します
+9. USERNAME の下にある TOKEN の Copy ボタンを押し、コピーされた Token をメモしておきます
+10. 下の方にある MESSAGE CONTENT INTENT のスイッチを選択し、青の状態にして Save Changes を押します
+11. 左のメニューの OAuth2 を押し、展開されて出てきた URL Generator を選択します
+12. SCOPES から bot にチェックを入れます
+13. BOT PERMISSIONS のうち、以下にチェックを入れます
+    - Manage Channels
+    - Read Messages/View Channels
+    - Send Messages
+    - Send Messages in Threads
+    - Add Reactions
+14. 一番下の GENERATED URL の Copy ボタンを押して URL をコピーします
+15. コピーした URL をブラウザで開き、導入するサーバを選択して、はい→認証を押します
+
+3.の手順で入れた名前、6.の手順で登録したアイコンがサーバ上でのボットの名前・アバターになります。好きな名前・アバターをお使いください。
+
+
+### Docker / docker-compose のインストール
+
+[公式ドキュメント](https://docs.docker.com/engine/install/ubuntu/)に従い Docker Engine / docker compose / docker buildx をインストールします。
+
+このままだと `docker` コマンドを実行するのに `sudo` が必要で手間なため、普段使いのユーザを `docker` グループに所属させます。
+
+```
+$ usermod -aG docker my-user-name
+```
+
+ユーザ情報を反映させるため一度再ログインします。
+
+### 設定
+
+#### mirakc の設定
+
+[できるmirakc](https://mirakc.github.io/dekiru-mirakc/latest/config/) の記載と./docker-compose/mirakc/config.yml.exampleを参考に、./docker-compose/mirakc/config.ymlを設定します。
+
+#### docker-compose の設定
+
+./docker-compose/docker-compose.yml の中で録画ファイルの保存先ディレクトリを ./docker-compose/mirakc/recorded にしています。必要に応じて書き換えるか、このディレクトリをシンボリックリンクにして別の場所を指すかすると良いです。
+
+#### dtv-discord-go の設定
+
+config.yml.exampleを元にconfig.ymlを作成します。設定ファイルはYAML形式になっています。基本的に書き換える必要があるのは discord.token だけです。ここに先の手順で控えておいた Discord Bot の Token を記載します。
+
+### 実行
+
+./docker-compose ディレクトリで `docker compose up -d` コマンドを実行すると起動します。マシンを再起動しても自動的に再度起動するようになっています。
+
+## 使い方
+
+初回起動後は mirakc が EPG 情報を取得したり、取得した情報を dtv-discord-go が一気に書こうとして Discord の Rate Limit にひっかかったりするため、かなりの時間がかかります。
+
+### 番組情報
+
+`録画-番組情報`というカテゴリーの下にmirakcで設定されたチャンネル名を小文字・半角化した名前でチャンネルが出来ているはずです。EPG情報が取得されると番組ごとに1発言でタイトルや内容などが投稿されます。
+（小文字になるのは Discord の仕様です）
+
+### 手動録画
+
+上記の番組ごとの発言に対して、📼(`:vhs:`)でリアクションすると、Bot が🆗(`:ok:`)リアクションを返します。このとき裏でmirakcに対して録画スケジュール登録をしているので、時間が来ると録画されます。
+
+### 自動検索
+
+`録画-通知・予約`というカテゴリーの下に`自動検索`というフォーラムが作成されています。このフォーラムに特定の形式でスレッドを投稿すると、その内容が自動検索機能の対象になります。投稿のタイトルは何でも構いません。本文は以下のように指定します。
+
+例1: 「NHK」を含む名前のチャンネルでタイトルに「ニュース」をタイトルに含む番組を自動検索する
+
+```
+チャンネル: NHK
+タイトル: ニュース
+```
+
+例2: 全チャンネルの「NEWS」をタイトルに含む番組を自動検索する
+
+```
+タイトル: NEWS
+```
+
+英数字は全角・半角、大文字・小文字を正規化して比較するので、区別されません。
+現時点ではチャンネル名と番組タイトルしか検索できませんが、いずれ拡張したいと思っています。
+
+EPGが更新される度にこれらのルールがチェックされ、ルールに合う番組が見つかると、そのスレッドにぶら下がる発言で見つかった番組の情報が投稿されます。
+
+スレッドの発言に対して📼リアクションをしても録画はされないので注意してください。発言の中にある URL が`録画-番組情報`の発言へのリンクなので、そちらのメッセージに対してリアクションをしてください。
+
+
+### 自動検索・通知
+
+自動検索で投稿した発言に対して、👀(`:eyes:`)でリアクションしておくと、ルールに合う番組が見つかったときの投稿にリアクションした人へのメンションが付与されます。見逃したくないときに利用してください。
+
+### 自動検索・録画
+
+同様に📼(`:vhs:`)でリアクションしておくと、ルールに合う番組が見つかったときの投稿と同時に、番組情報へ Bot が📼でリアクションし、録画がスケジュールされます。
+
+## 注意事項
+
+現時点では番組情報投稿、自動検索はEPGの更新で追加された番組情報に対してだけ有効です。途中で書き換わった番組情報については対処していません。また、自動検索のスレッドの投稿時に既に番組情報に投稿されている番組についてはまだ検索するようになっていません。
+
+録画予約について、チューナーの数を考慮していないため、チューナー数より多い数の番組を同時に録画予約した場合録画できない番組が出てきます。特に警告などもないので注意してください。
+
+番組情報の発言、自動検索結果については現時点ではログに残り続けます。過去の番組情報について📼リアクションをしても当然ながら録画出来ないので注意してください。特に警告などもありません。
+
+## TODO
+
+https://github.com/users/kounoike/projects/2/views/1 にもありますが、大きなものは以下
+
+- 自動検索スレッドに追加したときにその時点のEPGに対して検索をかけたい
+- 録画完了・失敗時の通知・発言を追加する
+- チューナー不足時の処理を考える
+- 過去の番組情報をどうするか考える
+- 自動エンコードなどの機能追加？
+
+
 

docker-compose/docker-compose.yml

@@ -0,0 +1,52 @@
+version: '3.8'
+services:
+  dtv:
+    image: ghcr.io/kounoike/dtv-discord-go:latest
+    environment:
+      TZ: Asia/Tokyo
+    links:
+      - tuner:tuner
+      - db:db
+  db:
+    image: mariadb:latest
+    volumes:
+      - mysql-db:/var/lib/mysql
+    # ports:
+    #   - "3306:3306"
+    environment:
+      MYSQL_USER: dtv-discord
+      MYSQL_PASSWORD: dtv-discord
+      MYSQL_ROOT_PASSWORD: dtv-discord
+      MYSQL_DATABASE: dtv
+      TZ: "Asia/Tokyo"
+    command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --performance-schema=false --expire_logs_days=1 --default-authentication-plugin=mysql_native_password
+    restart: always
+  tuner:
+    # image: mirakc/mirakc
+    build: ./mirakc/docker
+    privileged: true
+    # ports:
+    #   - "40772:40772"
+    volumes:
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro
+      - epg-db:/var/lib/mirakc/epg:rw
+      - ./mirakc/config/config.yml:/etc/mirakc/config.yml:ro
+      - ./mirakc/recorded:/recorded:rw
+    devices:
+      - /dev/px4video0
+      - /dev/px4video1
+      - /dev/px4video2
+      - /dev/px4video3
+      - /dev/bus
+    environment:
+      TZ: Asia/Tokyo
+      MIRAKC_DEBUG_CHILD_PROCESS: ''
+      RUST_LOG: 'info,mirakc=info'
+      MIRAKC_ARIB_NO_TIMESTAMP: ''
+      MIRAKC_ARIB_LOG: 'info'
+    restart: always
+
+volumes:
+  mysql-db:
+  epg-db: