kokorobeats 556LUNALINK — SHARE companion
正式名称：556LUNALINK（読み：ココロルナリンク）
=======================================

親機・子機のWallpaper Engine版で、SHAREを押した時の共有画像をPC内に保存する共通の補助機能です。
PC情報・WITH MUSICの計測とは別のプロセスで動き、計測用の補助機能を再起動しません。
SNSへの画像の自動アップロード・投稿は行いません。
任意のSpotify接続で、SHARE時の曲URLを読み取る機能を追加しました。

使い方
------
このかんたんキットでは隣のpythonフォルダーを使用し、Pythonの手動インストールは不要です。PC companionとペアリングした環境で、start.ps1を開始します。
隣にkokorobeats_pc_companionフォルダーがある場合は、その既存controlを読み取ります。
別の場所の既存controlを使う場合:
  powershell.exe -NoProfile -File .\start.ps1 -PCControlPath "C:\path\to\pc-companion.control.json"
接続トークンはそのcontrolから読み取り、起動引数やログへ出力しません。
既存control、壁紙のpc-link-config.js、音楽累計の保存内容は書き換えません。
終了は、このフォルダーのstop.ps1です。画像ファイルは削除しません。
配布版のスクリプト自体は、自動起動・サービス登録を行いません。
個人環境ではWindowsのスタートアップにstart.ps1のショートカットを登録し、
ログオン時に非表示で開始できます。SHAREとPC companionの起動順は固定する必要はありません。
初めて使う場合は、先にPC companionとのペアリングを済ませてください。

保存と共有
----------
SHAREの明示操作で、完成したPNGだけを受け取ります。
保存先はWindowsで設定されている「ピクチャ」内の
  kokorobeats 556LUNALINK\Share
です。日時・形式・ランダムな識別子でファイル名を作り、既存ファイルを上書きしません。
新しく保存するPNGのファイル名は556LUNALINK_で始まります。
以前の保存画像は「kokorobeats LUNA LINK\Share」に残ります。
X用は1080×1440、Instagram用は1080×1350、Story用は1080×1920です。
X用PNGは最大5MiB、ほかは最大10MiBです。
画像に含めたノード名・曲名・ジャケット等は、共有画像の一部として保存されます。
これらを別の履歴ファイルへ記録することはありません。

保存後、追加の明示操作でPC内の確認ページ・X・Instagramを既定ブラウザーで開けます。
3つのPNGをまとめたSHAREページでは、画像形式の選択でプレビューと保存画像を切り替えられます。
この画面は壁紙内ではなく、通常のブラウザーで操作します。
確認ページにはPNGのプレビュー、ダウンロード、SNSを開くリンクがあります。
画像はSNSの投稿画面に自動添付されません。保存したPNGを自分で選んでください。
投稿文の候補がある場合は、確認ページからコピーできます。
StoryはスマートフォンへPNGを渡して利用できます。
確認ページのURLはランダムな識別子で保護され、このPC内でのみ開けます。
URLを知る、このPCのほかのユーザーやアプリからは画像を見られます。
確認ページはこの補助機能が動いている間利用でき、再起動時にはURLの登録を破棄します。
PNGそのものは引き続きピクチャ内に残ります。

通信
----
127.0.0.1:8774だけで待機します。LAN・外部サーバーへ画像を送る機能はありません。
POST /v1/share は、形式・PNGデータURL・撮影IDまたは任意の短い投稿文候補を受け取ります。
POST /v1/share/capture は、撮影時刻・表示中の曲情報・楽曲表示のON/OFFを受け取ります。
接続済みのSpotifyに同じ曲が再生されている場合だけ曲URLを取得し、撮影IDに固定します。
リンクの取得はSHARE・撮り直しの明示操作時のみ。形式の切替や共有ページの表示では再取得しません。
POST /v1/share/open は、保存画像IDとbrowser / x / instagramの固定選択だけを受け取ります。
POST /v1/share/session は、x / instagram / storyの保存画像IDと初期表示形式だけを受け取り、
PC内で3形式を選べるSHAREページを作ります。画像IDと形式の対応を検証し、最大128組を保持します。
ページの作成や表示だけでブラウザーやSNSを開くことはありません。
組のIDを/v1/share/openに渡す場合はbrowserのみ指定できます。
いずれのPOSTも既存のX-OSM-Linkペアリングと、許可されたOrigin / Hostを照合します。
任意のURL、保存先、ファイル名、コマンドを指定することはできません。
SHAREの明示操作ごとに、起動時に指定したPC companionのcontrolだけを検証して読み直します。
接続キーが変わった時は古いキーを受け付けず、新しいキーへ追従します。SHAREの再起動は不要です。
controlが取得できない時や不正なcontrol・キーでは操作を受け付けません。
壁紙側から保存先やcontrolの場所を指定することはできません。
ポート8774が使用中なら起動に失敗し、ほかのプロセスを終了させません。

配布
----
配布するのはshare_server.py、share_portal.py、spotify_link.py、start.ps1、stop.ps1、README.txtだけです。
share-companion.control.json、share-companion.stop.json、*.log、__pycache__は含めません。
PC companionのcontrolやペアリングトークン、個人の保存画像も含めないでください。
.spotify-privateフォルダーの設定と認証情報は、絶対に配布ZIPへ含めないでください。

Spotifyへの初回接続
-------------------
SHAREの共有画面から「Spotifyを接続」を開きます。
Spotify Developer Dashboardで個人用のWeb APIアプリを作り、次のRedirect URIを登録してください。
  http://127.0.0.1:8774/spotify/callback
作成したClient IDを接続画面へ入力して保存し、Spotifyにログインして接続します。
Client Secretは不要です。読み取り権限はuser-read-currently-playingだけです。
アプリ所有者のPremiumアカウントが必要です。一般公開の子機への展開は、この利用条件とは別に検討します。
接続したら壁紙でSHAREをもう一度押してください。接続前の画像に、後から別の曲URLを付け足しません。

保存画像にQRコードやURL文字を加えることはせず、共有画面と投稿文へ曲URLを含めます。
共有画面の「曲を開く」「リンクをコピー」「投稿文をコピー」が使えます。
投稿文は次の書式です。アルバム名や曲URLを取得できない場合は、その行を省きます。
  「曲名 / アーティスト名」
  『アルバムタイトル』
  URL
  #556LUNALINK
Xは投稿文を添えた投稿画面を開きます。Instagramでは投稿文のURLは通常クリックできません。
ストーリーでは、リンクスタンプへ曲URLを貼り付けて使えます。
曲名・アーティスト・アルバム・再生状態・取得時刻などを照合し、不一致や取得失敗時はリンクを省きます。
Spotifyのローカルファイル、広告、ポッドキャストには曲リンクを付けません。

認証情報はこのPCのWindowsユーザーだけが復号できるDPAPI暗号化形式で保存します。
保存場所はこの補助機能の.spotify-privateフォルダーです。接続解除で保存した認証情報を削除します。
音声・画像・PC実測値をSpotifyへ送信しません。Spotifyの再生操作や履歴の収集は行いません。
通信先はSpotify公式の認証・トークン・現在再生中の曲APIに限定します。
