私のホームページに鼓動がある
My Homepage Has a Pulse (snehankekre.com)
要約
著者は、自身のホームページにリアルタイムの心拍数を表示する小さな赤いハートのアイコンを設置しました。この心拍数は、Garminのスマートウォッチから取得され、ホームページの更新時に表示されます。当初は単なる「オンライン」ステータス表示を求めていましたが、最終的には個人の生理的データを公開することへの同意と、そのパーソナルな性質に価値を見出しています。
全文翻訳
My homepage has a pulse
私のホームページに、鼓動する小さな赤いハートが表示されるようになりました。その横の数字は私の実際の心拍数であり、ハートはそれに連動した頻度で鼓動します。48 bpm なら1.25秒に一度、80 bpm なら0.75秒に一度という具合です。これを書こうと思ったのは、単にやりたかったからですが、結果として予想以上に興味深い設計上の決断が含まれていました。
The watch
私はGarmin Descent Mk3i(43mm、カーボンブラックDLCチタン)を着用しています。これは、テクニカルダイビングやケーブ、沈船のようなオーバーヘッド環境では冗長性が必要だからです。もし75mのケーブ内でダイブコンピューターが故障したら、すぐに浮上して充電することはできません。ケーブダイバーはバックアップのバックアップを持っています。2025年4月以降、私はこれを使って100mまでの400本以上のダイビングを行いました。
充電中やシャワーを浴びている時以外は、ほとんど外しません。ダイビングの合間には、心拍数、睡眠スコア、HRV、歩数、消費カロリーなど、数十種類のバイタルデータを24時間体制でトラッキングし、それらをすべてPixel 9 Pro上のGarmin Connectアプリに同期しています。ジムやストリートリフティングのセッションも記録されます。つまり、Garminは私の人生の連続的で詳細な生理学的記録をすでに保持しているのです。あとは、そのデータをGarminから取り出して、私のホームページに表示するだけでした。
A more personal “online” status indicator
昔のメッセージングアプリには緑色のドットがありました。Facebook Messengerや、それ以前のGchatには、その人が今オンラインであることを示す小さなインジケーターがありました。2012年にHexChatでそれを見たのを覚えています。このサイトにもそれを求めていましたが、緑色のドットは常に「ソケットの状態」を示すものであって、「人」を示すものではないと感じていました。心臓の鼓動は、「オンライン」であることの最も抽象度の低い表現です。「ブラウザの接続が開いている」ことと、「生きている、そしてその証拠がある」ことの違いです。結局はページ上のただの数字ですが、それは私の数字であり、私の胸から来るものなので、サイト上で最もパーソナルなものになります。多くの人にとっては少しキザに聞こえるかもしれませんが、私はこのアイデアが好きです :P。
長期的な目標は、いつかこのサイトに、私の人生の詳細な記録を公開することです。ワークアウト、睡眠、HRV、消費カロリー、歩数などです。それがどのような情報を漏洩させるかは理解しています。終日の心拍数は、私がいつ眠り、いつ起きるかを示します。データの欠落やタイムゾーンの移動は旅行を示唆します。安静時心拍数が8 bpm上昇するのは、病気、ストレス、あるいは昨夜の飲みすぎを示唆します。HRVのトレンドは精神状態の良好な代理指標となり、定期的なジムのスケジュールは私がいつ家にいないかを正確に示します。私はそれらすべてを受け入れ、問題ないという判断を下しました。私はそれに同意します。もしあなたがそれに問題を感じるなら、それはあなたの問題であり、私の問題ではありません ¯*(ツ)*/¯。
Surely someone has done this. Yup, they have.
最初に考えたのは、これはすでに存在するだろうということでした。そして、その通りでした。Twitchのストリーマーは、PulsoidやHypeRateのようなサービスを通じて、何年も前からライブ心拍数を画面に表示しています。どちらもGarminウォッチに対応しています。これらは、ウェアラブルデバイスをブロードキャスト心拍数モードにして、BLE/ANT+経由でスマートフォンアプリにストリーミングし、その数値をサーバーに中継する仕組みです。最初は有望に見えましたが、私にとっては行き止まりでした。Garminのマニュアルでは、ブロードキャストはバッテリー寿命を縮めると警告しており、この時計は私のダイブコンピューターです。ウェブサイトのウィジェットのために、ダイビング当日のバッテリーを犠牲にするわけにはいきません。それに、ブロードキャストは一度オンにしたら、その範囲内に留まる必要があるモードです。私にとっては面倒すぎるように思えました。それに、週に一度充電すれば10日間持つという点が気に入っています。ウィジェットを動かすためだけに毎晩充電したくはありません。
ブラウザ自体はBluetoothで通信できます。これは一時的に有望に見えました。Web Bluetooth APIは、近くのデバイスから標準的な心拍数GATTサービスを直接読み取ることができます。しかし、これは訪問者のブラウザを訪問者の近くのデバイスに接続するため、やはりうまくいきませんでした。これは私のマシン上で、Chromiumブラウザを使用し、時計がブロードキャストモードの場合にのみ機能するでしょう。
ならば、きっと本物のAPIがあるはずです。あります。GarminのHealth APIはこのデータを提供しますが、アクセスはビジネスアプリケーションと審査によって制限されています。これは、ウェアラブルデバイスを製品に統合する企業向けに作られています。ホームページにハートを表示したいだけの人間はどうすればいいのでしょうか? ファーッ (╯’□’)╯︵ ┻━┻。
この時点で、最初にやるべきだったことを行いました。GitHubとRedditで検索したのです。Redditのスレッドで、2つのプロジェクトが繰り返し現れました。GarminDBは、Garminの履歴全体をローカルSQLiteデータベースにダウンロードし、分析やグラフ表示を提供します。素晴らしいですが、今回の目的には合いません。スキーマを持つアーカイブはやりすぎのように思えます…おそらく、毎朝1日分の心拍数データをJSONで取得したいだけなのです。python-garminconnectは、Garmin Connectアプリと同じプライベートAPIを使用するPythonクライアントなので、適切なツールです。アプリと同じようにログインでき、アプリと同じエンドポイントを呼び出します。これは、私が携帯電話で見ることができるほぼすべてのものを公開しており、偶然にも将来のプロジェクトの問題を解決します。ワークアウト、睡眠、HRVすべてが同じクライアントからアクセス可能です。素晴らしい、@cyberjunkyさん、ありがとうございます!
Why not live?
ライブ表示は実際には選択肢としてありませんでしたが、当初はそれを知りませんでした。時計はデフォルトではどこにもストリーミングしません。終日の心拍数は手首に蓄積され、時計と電話の同期が行われるたびに、Garminのサーバーにバッチで送信されます。ブロードキャストモードなしでは、購読できるフィードはありません。そして私のサイトは静的で、Astroで一度ビルドされ、GitHub Pagesからファイルとして提供されます。WebSocketを開いたままにしておくサーバーがないため、たとえ時計がストリーミングしたとしても、訪問者にそれを中継する方法を見つけられませんでした。唯一の選択肢は、1日に一度データを取得して再生することです。
したがって、妥協点として、ウィジェットは昨日を再生します。あなたの時間で14:32に私のホームページをロードすると、昨日の14:32の私の心拍数が、実際のサンプルから補間されて表示されます。「ライブ」というラベルは白々しい嘘ですが、それは私が語る嘘です。しかし、少なくとも嘘は正確です。オフセットは正確に24時間、データは本物であり、測定値の間の直線を描く以外は何も作り上げられていません。
A one-time login (for a year)
python-garminconnectはメールとパスワードでログインしますが、返されるのはOAuthトークンのペアです。OAuth1トークンは長期間有効で、約1年間有効です。OAuth2トークンは実際にAPI呼び出しを認証するもので、数時間で期限切れになります。ライブラリはすべてのリクエストをOAuth2トークンで署名し、それが期限切れになるたびに、裏側でOAuth1トークンを使用して新しいトークンを生成します(私の限られた理解では)。そのため、私の認証情報は一度ラップトップに入力され、CIに決して渡されることはありません。CIは、自身でリフレッシュするトークンのみを1年間保持します。
一度限りのログインは以下のようになります。
python3 -m venv .venv
source .venv/bin/activate.fish
pip3 install garminconnect
python3 scripts/garmin_login.py
garmin_login.pyは、認証情報を求め、トークンの処理を行う短いスクリプトです。興味深い部分はこちらです。
garmin = Garmin(email=email, password=password, return_on_mfa=True)
status, client_state = garmin.login()
if status == "needs_mfa":
mfa = input("MFA code: ")
garmin.resume_login(client_state, mfa)
garmin.client.dump(str(tokendir)) # token files -> ~/.garminconnect
b64_path.write_text(garmin.client.dumps()) # same tokens, one base64 string
return_on_mfa=Trueは、Garminが2要素認証コードを求めた場合にライブラリが終了するのではなく、一時停止して制御を戻すようにし、resume_loginで入力したコードでハンドシェイクを完了します。最終的にトークンは2つの形式で保存されます。ローカル実行用の~/.garminconnectのファイルとして、そしてGitHub Actionsのシークレットとなる単一のbase64ブロブ(client.dumps()はトークンストア全体を1つの文字列にシリアライズします)。
gh secret set GARMINTOKENS_BASE64 --repo snehankekre/snehankekre.github.io < ~/.garminconnect.b64
ログインには問題がありました。Garminは試行中に私のIPをレート制限しました。Mullvadのサーバーをローテーションしてもです。ライブラリはログイン戦略のチェーンを試行し、最初の2つ(mobile+cffi、次にmobile+requests)はどちらも429(「GarminによるIPレート制限」)を返しました。幸いなことに、ライブラリのチェーンの下の方にあるフォールバック戦略が成功しました。いずれにせよ、これは一度限りの代償でした。CIはまったくログインせず、トークンを再生するだけなので、ログインエンドポイントは二度と見られません。
Fetching yesterday, every morning
私のサイトはAstroを使用しており、Actionsワークフローによってビルドされ、GitHub Pagesにデプロイされます。CIがサイトをビルドするなら、ビルドの直前にCIがデータを取得し、データは他のすべてのものと同様に静的ファイルとして出荷されると考えました。そのため、ビルドの前に実行される小さなPythonスクリプト、fetch_hr.pyがあります。その中核部分は以下の通りです。
tokens = (
os.environ.get("GARMINTOKENS_BASE64", "").strip()
or os.environ.get("GARMINTOKENS", "~/.garminconnect")
)
garmin = Garmin()
garmin.login(tokens)
tz = ZoneInfo(os.environ.get("HR_TZ", "Asia/Makassar"))
target = (datetime.now(tz) - timedelta(days=1)).date()
data = garmin.get_heart_rates(target.isoformat())
points = [
[ts, bpm]
for ts, bpm in (data.get("heartRateValues") or [])
if bpm is not None
]
garminconnect 0.3.xは、login()呼び出しでトークンディレクトリまたはbase64ブロブのいずれかを受け入れます。512文字より長い文字列はブロブとして扱われ、それより短い文字列はパスとして扱われます。これは、私のMac(~/.garminconnectを読み取る)とCI(シークレットを読み取る)で同じスクリプトが実行され、私の側で分岐がないことを意味します。
タイムゾーンの部分は、私にとって少し難しい問題でした。これがうまくいかないと、サイレントに間違ったデータを提供してしまう可能性がありました。GitHubランナーはUTCで動作します。私のバリの午前3時のcronはUTCの19:00に実行されますが、これはUTCではまだ「前日」です。そのため、水曜日の午前3時に私のタイムゾーンで、ナイーブなdate.today() - timedelta(days=1)をランナーで計算すると月曜日になり、2日前の心拍数を再生してしまうことになります。「昨日」は私の手首があるタイムゾーンで計算する必要があります。そのため、HR_TZ=Asia/Makassarをワークフローから渡しています。これにより、次に移動した際に一行で変更できるようになります。
if bpm is not Noneのフィルターも重要です。時計が手首から外れている場合、Garminは何も記録しないのではなく、nullを記録するため、データの穴を「穴のように」見せたいのです(詳細は後述)。生き残ったものがpublic/hr.jsonに書き込まれます。約14KBです。
{"date":"2026-07-13","resting":48,"points":[[1783872000000,56],[1783872120000,56],...]}
約717サンプル、約2分に1つ、タイムスタンプは絶対エポックミリ秒GMTです。その絶対性が後で重要になります。
2分間隔についての一言、これは私を混乱させました:これは時計が測定する頻度ではありません。光学センサーは1秒間に複数回サンプリングし、Garminの公式Health API(制限付きのもの)は終日の心拍数を15秒ごとの代表サンプルとして提供します。2分間隔のシリーズは、Connectアプリの日次チャートエンドポイントが集約するものであり、python-garminconnectが読み取るエンドポイントがそれであるため、それが私が取得するものです。もしHealth APIにアクセスせずに2分未満の解像度が必要になった場合、検討する可能性のあるパスがあります。記録されたアクティビティ(ダイビング、ジムセッション)は、1秒サンプルのFITファイルとして保存され、python-garminconnectはそれらもダウンロードできます。しかし、今のところ2分間隔で十分です。
スクリプトに与えたもう一つのルールは、失敗しないことです。本体全体は1つのtry/exceptブロック内で実行され、以下のように終わります。
except Exception as e: # never break the build
print(f"hr fetch skipped: {type(e).__name__}: {e}")
return 0
時計が同期しなかった、トークンが期限切れになった、あるいはGarminがダウンしていた場合、理由をログに記録し、終了コード0で何も書き込みません。ビルドは続行され、ウィジェットはデータを見つけられずに非表示になります。
ワークフロー側は、2つのcronトリガーとAstroビルドの前の1つのステップです。
schedule:
# 03:00 in Bali, once the day is complete,
# and 12:00 to catch a late phone sync.
- cron: '0 19 * * *'
- cron: '0 4 * * *'
- name: Fetch heart-rate data
env:
GARMINTOKENS_BASE64: ${{ secrets.GARMINTOKENS_BASE64 }}
HR_TZ: Asia/Makassar
run: |
pip install --quiet garminconnect==0.3.6
python scripts/fetch_hr.py
バージョンは0.3.6に固定されています。これは非公式のプライベートAPIクライアントであるためです。トークン処理とレスポンスの形状をその正確なバージョンに対して検証しました。将来の破壊的な変更が静かにドリフトするよりも、大きな音で失敗する方が良いでしょう。JSONはpublic/に配置され、Astroはpublic/をそのままビルドにコピーし、GitHub Pagesは他のファイルと同様にそれをサーブします。コミットする必要はありません。public/hr.jsonはgitignoreされており、リポジトリに1年分の心拍数の差分が蓄積されることはなく、データはデプロイされたアーティファクト内にのみ存在します。
Replaying it exactly 24 hours later
クライアント側は、ページにインライン化された約40行のバニラJSです。ブラウザは/hr.jsonを取得し、10秒ごとに単一のターゲットインスタントを評価します。
const bpm = sample(Date.now() - 86_400_000);
その減算が、前のエポックミリ秒の詳細が重要だった理由です。GarminのタイムスタンプとDate.now()はどちらも絶対GMTミリ秒なので、東京の訪問者とニューヨークの訪問者は同じ質問、「ちょうど24時間前の彼の心臓はどうしていたか」を尋ね、同じ正しい答えを得ます。
sample()の全体像です(リポジトリ版にはTypeScriptアノテーションがありますが、ここでは省略しています)。
const first = pts[0][0];
const last = pts[pts.length - 1][0];
const DAY = 86_400_000;
const GAP = 20 * 60 * 1000; // holes wider than this are "no signal"
const sample = (t) => {
if (t > last) t -= DAY; // just past the data day (pre-refresh); replay it
if (t < first - GAP || t > last + GAP) return null;
let prev = null;
let next = null;
for (const p of pts) {
if (p[0] <= t) prev = p;
else { next = p; break; }
}
if (!prev) return next && next[0] - t <= GAP ? next[1] : null;
if (!next || next[0] - prev[0] > GAP) return t - prev[0] <= GAP ? prev[1] : null;
const f = (t - prev[0]) / (next[0] - prev[0]);
return Math.round(prev[1] + f * (next[1] - prev[1]));
};
はい、これはペアを見つけるためにO(n)の線形スキャンであることを知っています。10秒ごとに717ポイントです。しかし、ここでバイナリサーチを使っても、賢さ以上のメリットはありません。
Garminは約2分ごとにサンプリングし、2分に1回しか変化しない数値は死んでいるように見えます。訪問者にとっては退屈でしょうし、私にとっても退屈です。ウィジェットが動くのを見たいからです。そのため、ターゲットインスタントを挟む2つの実際のサンプルの間で、ウィジェットはそれらを結ぶ直線から数値を読み取ります。例えば、ターゲットtが10:00:50で、10:00:00の62 bpmのサンプルと10:02:00の68 bpmのサンプルの間にあるとします。
68 ┤ ● next
│ ◌ ← reading at t
62 ┤ ● prev
└─┬────────┬───────────┬──
10:00 10:00:50 10:02
横断する割合はf = 50/120 ≈ 0.417で、読み取り値は62 + 0.417 × (68 − 62) = 64.5となり、65に丸められます。
const f = (t - prev[0]) / (next[0] - prev[0]); // 0 at prev, 1 at next
return Math.round(prev[1] + f * (next[1] - prev[1]));
10秒ごとに進むと、値は62、63、63、64、65と、その線分上を移動します。表示されるすべての値は、2つの実際の測定値の間の直線上にあり、これはGarminアプリ自身の毎日のグラフが描画するものと同じです。
しかし、補間には、挟むサンプルが隣接しており、2分間隔であるという隠れた仮定があります。データには実際の穴があります。時計が充電器の上にあったり、シャワー中にシンクの上に置かれていたりすることがあり、Garminは何も記録しない代わりにnullを記録します。例えば、14:00から17:00まで時計が外されていたとします。ナイーブなコードは14:00の71 bpmと17:00の58 bpmを取り、滑らかで、もっともらしく、完全に作り上げられた数値を3時間分補間してしまうでしょう。ガードは私が20分に設定した閾値です。したがって、ターゲットを挟む2つのサンプルがそれよりも離れている場合、ウィジェットは補間を拒否して非表示になります。20分は、データの通常のケイデンスよりも十分に広いです。私の1日分のデータをチェックしました。716個の連続サンプルのうち715個は、夜間を含めて正確に2分間隔であり、唯一の例外は09:20の8分間のギャップで、これはほぼ間違いなく私のシャワーだったでしょう。したがって、通常のデータはこのガードに引っかかることはなく、実際のギャップがウィジェットをすぐに隠すのではなく、3時間前の数値を現在のものとして提示するほど狭くはありません。
最後の問題は深夜です。ファイルはバリの暦日をカバーし、午前3時にリフレッシュされるため、深夜からリフレッシュまでの間、now - 24hはデータの終端を過ぎてしまい、ウィジェットは毎晩消えてしまうでしょう。これは同じ場所にある1行の修正で済みます。
if (t > last) t -= DAY; // just past the data? replay the same time, one day earlier
午前1時30分の訪問者は、何も表示されない代わりに、2日前の午前1時30分を一時的に取得します。これは、再生が前提のウィジェットにとっては公正な取引と言えるでしょう。私が気に入っているのは、この同じ行がステールネスガードでもあることです。なぜなら、最大でも一度しか巻き戻らないからです。パイプラインが停止してファイルが数日間ステールになった場合でも、巻き戻されたターゲットはデータに到達せず、ウィジェットは非表示になります。ラップアラウンドは最大24時間の猶予を与え、1週間前のデータを現在のものとして表示することはありません。
失敗した場合にステールな数値を表示するのではなく、ウィジェットを非表示にすることにしました。ウィジェットのマークアップは既にhidden属性が付いた状態で出荷され、正常なフェッチと有効なサンプルのみがそれを削除します。フェッチ失敗、空のファイル、ステールなデータ、サンプルの穴はすべて、ウィジェットが非表示のままになる結果となります。
Making it beat
鼓動は、データと同じ頻度でハートのグリフを拡大・縮小するCSSアニメーションです。ティックごとに、スクリプトは数値をDOMに書き込み、CSSカスタムプロパティをビート間隔、60/bpm秒に設定します。
bpmEl.textContent = String(bpm);
heartEl.style.setProperty('--beat', `${(60 / bpm).toFixed(3)}s`);
アニメーションはこの変数を読み取るだけなので、ページ上のハートはデータが示すレートで鼓動します。48 bpmは80 bpmよりも明らかに遅く鼓動します。
.hr-heart {
display: inline-block;
color: var(--hr-heart);
transform-origin: 50% 60%;
animation: hr-beat var(--beat, 1s) ease-out infinite;
}
@keyframes hr-beat {
0% { transform: scale(1); }
14% { transform: scale(1.32); }
28% { transform: scale(1); }
42% { transform: scale(1.18); }
56%, 100% { transform: scale(1); }
}
キーフレームは収縮期/拡張期サイクルを模倣しており、大きなバンプ、次に小さなバンプ、そして残りのサイクルは休息となります。なぜなら、単一の対称的なスケールパルスは、通知バッジのように見え、ハートのように見えなかったからです。transform-origin: 50% 60%は、グリフが境界ボックスの中心ではなく、視覚的な中心から膨張するようにします。そして、prefers-reduced-motionはアニメーションを完全に無効にします。OSでモーションを減らすように要求している人には、数値は引き続き更新されます。
What does this cost me? Nothing, really.
サーバー(GitHub Pagesを除く)、サードパーティのリレー、時計のバッテリーへの影響はありません。時計は以前と同じように同期します。私は時計を着用し、電話に同期し、電話はGarminのサーバーに同期します。追加された違いは、CIが1日に一度Garminのサーバーからデータを取得し、サイトに送信することです。すべては、1つのPythonスクリプト、2行のcron、そしていくつかのJavaScriptで構成されています。予想される唯一のメンテナンスは、約1年後にトークンが期限切れになることです。その時点で、ハートは静かにホームページから消え、私はログインスクリプトを再度実行することになります。Googleアシスタントに11ヶ月後にリマインダーをセットするように頼みました :D。
いつか、余裕ができたら、ワークアウトやその他の記録を追加するでしょう。私の心拍数を取得するのと同じクライアントが、私が記録したすべてのジムセッションやストリートリフティングセッションを取得できるため、ここの配管のほとんどは引き継がれます。そして、アクティビティは1秒サンプルのFITファイルとしてダウンロードされるため、ワークアウトセクションは終日のシリーズよりもはるかに詳細になる可能性があります。それまでは、私の心拍数を正確に24時間遅れでお届けします。