transistor

transistor — ターミナルから Transistor.fm のポッドキャストをホスティング

Transistor.fm アカウントを v1 JSON:API 経由で操作します。番組、エピソード、 下書きから公開までのライフサイクル、日別ダウンロード分析、プライベートポッドキャストの 購読者、Webhook に対応しています。レスポンスは JSON:API ドキュメントです。付属の CLI は 生の形式を維持しつつ、エージェントが jq で使える形で展開します（--json）。 書き込みコマンドにはガードが設けられています。エピソードは必ず下書きとして作成され、 公開には専用のエンドポイントを使用します。

セットアップ

1. Transistor ダッシュボードの Account page → API Access（https://dashboard.transistor.fm/account）で API キーを確認し、環境変数に設定します：

export TRANSISTOR_API_KEY="<API_KEY>"

2. キーを検証します（認証確認用の GET /v1。/v1/user ルートはありません）：

transistor user          # name and time zone
transistor user --json | jq '{id, name, time_zone}'

キーには、ポッドキャストごとに、そのユーザーのダッシュボード上のロール（オーナー／管理者／チームメンバー）が適用されます。--help と --dry-run は認証情報がなくても動作します。リクエストは 10 秒あたり 10 回にレート制限されており、CLI はリクエストを連続送信するのではなく、明確な 429 メッセージを表示して終了します。

基本コマンド

user — 認証確認

transistor user                # who does this key belong to?
transistor user --json

shows / show — ポッドキャストを参照

transistor shows                          # newest-updated first
transistor shows --private --json         # private podcasts only
transistor show --id <SHOW_ID_OR_SLUG>    # full attributes incl. feed_url
transistor shows --page 1 --per 20 --json

ほとんどの番組スコープのルートでは、番組 ID とスラッグを相互に使用できます。番組リソースにはカウント用のフィールドがありません。episodes --show ... --json で件数を取得し、meta.totalCount を確認してください。

episodes / episode — エピソードを参照

transistor episodes                                    # newest first, all shows
transistor episodes --show <SHOW_ID> --status draft    # drafts for one show
transistor episodes --show <SHOW_ID> --per 50 --page 1 --json
transistor episode --id <EPISODE_ID> --include show    # compound doc + parent show

--include show を指定すると included[]（JSON:API の複合ドキュメント）が追加されます。--json 出力の各エピソード項目には、すでにリレーションシップから解決された show_id が含まれています。古いスクリプトとの互換性のため、--limit は --per のエイリアスとして使用できます。

episode-create / episode-update — 下書きとメタデータ

transistor episode-create --show <SHOW_ID> --title "Ep 12: Roasting" \
  --season 2 --number 4 --audio-url "https://uploads.example.com/ep12.mp3"
transistor episode-update --id <EPISODE_ID> --title "New title"
transistor episode-update --id <EPISODE_ID> --audio-url "<AUDIO_URL>"   # attach audio

episode-create は常に下書き（status: "draft"、published_at: null）として作成し、公開することはありません。episode-update はメタデータを変更するか音声を添付するもので、公開状態には一切触れません。

episode-publish — ライフサイクルの切り替え

transistor episode-publish --id <EPISODE_ID>                       # publish now
transistor episode-publish --id <EPISODE_ID> --status scheduled \
  --published-at "2026-09-03 09:00:00"                             # schedule
transistor episode-publish --id <EPISODE_ID> --status draft        # unpublish

専用エンドポイントとしてドキュメントに記載されている PATCH /v1/episodes/<EPISODE_ID>/publish に episode[status]=draft|scheduled|published を送信します。media_url が空のエピソードは、再生できない項目がすべての購読者のフィードに表示されるため、CLI は公開を拒否します。上書きするには --force を指定してください。

authorize-upload — ローカル音声（最大 5GB）

transistor authorize-upload --filename ep12.mp3                 # plan only
transistor authorize-upload --filename ep12.mp3 --file ./ep12.mp3

署名付き PUT を返します（--file を指定した場合は PUT も実行します）。表示される audio_url を episode-create／episode-update で添付します。署名付き URL の有効期限は切れます（ドキュメントの例では約 600 秒）。

analytics / episode-analytics — 日別ダウンロード数

transistor analytics --show <SHOW_ID>                        # last 14 days
transistor analytics --show <SHOW_ID> \
  --start-date 01-08-2026 --end-date 28-08-2026 --json
transistor episode-analytics --id <EPISODE_ID> --json

日付は dd-mm-yyyy 形式で、開始日と終了日のペアで指定する必要があります。分析属性は合計値ではなく日別の downloads[] 配列です。CLI はこれらを合計して downloads_total に格納し、生の配列も保持します。

subscribers — プライベートポッドキャストの視聴者

transistor subscribers --show <SHOW_ID> --json
transistor subscriber-create --show <SHOW_ID> --email "[email protected]"
transistor subscriber-batch --show <SHOW_ID> --email "[email protected]" --email "[email protected]"
transistor subscriber-delete --show <SHOW_ID> --email "[email protected]"   # or --id

webhooks — ポーリングではなくプッシュ通知

transistor webhooks --show <SHOW_ID>
transistor webhook-create --show <SHOW_ID> --event episode_published \
  --url "https://example.com/hooks/transistor"
transistor webhook-delete --id <WEBHOOK_ID>

イベント：episode_created、episode_published、subscriber_created、subscriber_deleted。アカウントあたりの上限：50。10 秒あたり 10 リクエストの制限があるため、最新情報を得るにはポーリングより Webhook が適しています。

グローバルフラグ

transistor --json shows                        # flags work in any position
transistor --dry-run episodes --show <SHOW_ID> # request plan, zero network
transistor --force episode-publish --id <EPISODE_ID>   # skip the audio guard
transistor --quiet shows                       # suppress non-essential output
transistor --verbose episodes                  # detailed stderr logging

--dry-run は {"dry_run": true, "method", "path", "params"} を出力します（書き込みコマンドでは、送信される正確な body も追加されます。角括弧付きのキーも含みます）。そのため、API にアクセスする前に計画を確認できます。--help と --dry-run は認証情報を必要としません。

パイプラインのレシピ

作成、音声の添付、公開（基本的なワークフロー）

export TRANSISTOR_API_KEY="<API_KEY>"
SHOW=$(transistor shows --json | jq -r '.shows[0].id')          # string id
AUDIO=$(transistor authorize-upload --filename ep12.mp3 --file ./ep12.mp3 --json | jq -r '.audio_url')
EP=$(transistor episode-create --show "$SHOW" --title "Ep 12" \
     --audio-url "$AUDIO" --json | jq -r '.id')                 # draft id
transistor episode-publish --id "$EP"                           # dedicated endpoint
transistor episode --id "$EP" --json | jq '{status, media_url, published_at}'

各ステージの出力を次のステージに渡します：shows → 文字列の id、 authorize-upload → 文字列の audio_url、episode-create → 文字列の下書き id、episode-publish → 最終的な status。音声にすでに公開 URL がある場合は、ステージ 2 を省略できます（その URL を直接 episode-create に渡します）。

下書きの確認：まだ公開されていないものは？

transistor episodes --show <SHOW_ID> --status draft --json \
  | jq -r '.episodes[] | [.id, .title, (if .media_url == "" then "no-audio" else "ready" end)] | @tsv'
# publish the ready ones (rate limit: 10 req / 10 s — add sleep 1 between calls)

週間ダウンロードレポート

transistor shows --json | jq -r '.shows[].id' | while read -r S; do
  transistor analytics --show "$S" --json \
    | jq -r --arg id "$S" '[$id, (.downloads_total|tostring)] | @tsv'
  sleep 1
done

JSON と jq

--json のキーは、JSON:API ドキュメントを安定した snake_case でラップします。 shows／episodes／subscribers／webhooks（meta が付属する配列）、 単一リソースのフラットなオブジェクト、プラン用の dry_run／method／path／params／body です。 属性名は Transistor 独自の名前（status、season、 number、duration（秒）、media_url、share_url、published_at、 feed_url）のままなので、jq のセレクターを api.transistor.fm に対する生の curl にそのまま適用できます。コレクションのページネーションは meta.currentPage／meta.totalPages／meta.totalCount として表示されます。例： transistor episodes --show <SHOW_ID> --json | jq -r '.episodes[] | [.id, .title, .status] | @tsv'。複合ドキュメントでは、CLI が リレーション（show_id）を解決し、人間向けモードでは included に 番組の概要を出力します。生の curl では、type と relationships.show.data.id を使って included[] を照合してください。

既知の注意点

• 公開は独立したエンドポイントで行い、副作用としては発生しません — POST /episodes と PATCH /episodes/:id では status を変更できません。エピソードが 下書きのままの場合、必要なのは PATCH /v1/episodes/<ID>/publish による episode[status]=published の設定です。（事前の CLI には公開機能が ありませんでした。）
• ユーザーの確認には GET /v1 を使います — /v1/user と /v1/authorization は 404 を返し、ユーザーリソースにはメール属性がありません（あるのは name と time_zone のみです）。
• ページネーションには pagination[page] と pagination[per] を使います（デフォルトは 0 と 10 で、ドキュメントの例では page 1 をリクエストしています）。pagination[limit] と page[number] は黙って無視されるため、これらを使うループでは page 1 を 何度も読み込むことになります。meta.currentPage < meta.totalPages の間、ループしてください。
• 番組リソースには件数が含まれません — 絞り込んだ一覧の meta.totalCount から エピソード数／購読者数を算出してください。
• 分析データは合計値ではなく日ごとの配列です — attributes.downloads を合計してください（CLI では downloads_total が提供されます）。日付の範囲は dd-mm-yyyy 形式で、 2 つずつ指定します。行の日付形式は解析しないでください（ドキュメントの例は セクション間で一貫していません）。
• 番組の作成はダッシュボードでのみ可能です — POST /v1/shows はありません。 番組を書き込めるのは show-update のみです。
• レート制限は 10 秒あたり 10 リクエストです — 429 が返されると、10 秒間アクセスできなくなります。再試行用ヘッダーはありません。間隔を空け、 購読者のインポートをまとめて行い、レスポンスをキャッシュし、最新状態の取得にはウェブフックを使ってください。Transistor は、API をウェブサイトのバックエンドとして使うことを明示的に禁止しています（その場合は RSS フィードを解析してください）。
• episode[published_at] には UTC ではなく番組のタイムゾーン（番組の属性）が使われます。予約公開と過去日付での公開のどちらも、公開エンドポイントを使います。
• 音声処理は非同期です — 音声を添付した後、audio_processing／ processing_failure を確認してください。未処理または失敗したファイルを公開すると、購読者には無音が配信されます。
• 署名付きアップロード URL の有効期限は約 600 秒です（ドキュメントの例）：認証を行い、返された content_type を使って PUT し、すぐに添付してください。
• エラーボディの正式な仕様はありません — CLI は JSON:API の errors[] 配列と、単独の {"message": ...} オブジェクトを処理し、どちらも 1 行の stderr にまとめます。401（キーの誤り）、403（ロール）、404（ID／ルートの誤り）、429 （レート制限）には、それぞれ異なるヒントが表示されます。

使用する場合

API を通じて Transistor.fm アカウントの情報を読み取ったり操作したりする場合は、このスキルを使います。API アクセスの確認、番組／エピソード（下書きや複合ドキュメントを含む）の閲覧、エピソードのライフサイクルの実行（作成 → 音声の添付 → 公開／予約公開／公開停止）、ダウンロード分析期間の取得、非公開ポッドキャストの購読者のインポートまたは取り消し、ウェブフックの登録などが含まれます。

使用しない場合

他のポッドキャストホスティングサービス（Buzzsprout、Libsyn、 Megaphone、Spotify for Creators — それぞれ独自の API／ツールを使用してください）には、このスキルを使わないでください。音声の制作や編集（ffmpeg と DAW の領域）、一般的な RSS フィードの解析やウェブサイトの描画（フィード XML を直接解析してください。Transistor は API をバックエンドのデータソースとして使うことを推奨していません）、新しい番組の作成（API ではできず、ダッシュボードで行います）、プラットフォームレベルの配信に関する質問（Apple／Spotify への申請はダッシュボードと RSS に関する作業です）にも使わないでください。

参照ファイル

ファイル	用途
references/auth-and-basics.md	x-api-key 認証、キーの場所とロールのスコープ設定、jq のパターンを含む JSON:API エンベロープ（data/attributes/relationships/included[]）、ページネーションのパラメーター、エラーの発生箇所
references/endpoint-catalog.md	各ルートのメソッド、パス、パラメーター（番組、エピソード、公開、アップロード、分析、登録者、Webhook）と、存在しないルート
references/episode-publish-lifecycle.md	下書き／予約済み／公開済みの状態遷移、公開リクエスト／レスポンスの正確な形式、CLI と curl での作成→音声→公開のレシピ、authorize-upload の迂回手順
references/gotchas-and-recipes.md	症状 → 原因 → 対処法をまとめたフィールドガイド（404 のユーザールート、気付かれにくいページネーション、429 の連発など）と複数ステップのワークフロー（一括予約、分析レポート、登録者のインポート、Webhook）

利用可能なスクリプトと前提条件

• scripts/transistor — 同梱の Python CLI（--json、--dry-run、 --force、--quiet、--verbose、--help をどの場所でも使用できます）。標準ライブラリと requests のみをインポートし、書き込みボディをドキュメントどおりに送信します （角括弧形式のキーを使うフォームフィールド）。
• scripts/test_transistor.py — オフラインテストスイート（pytest と unittest に対応）。すべての HTTP リクエストを用意された JSON:API ドキュメントでモックし、 ネットワークへの送信はゼロで、ライブ呼び出しのテストケースはありません（Transistor はキー認証が必要な API です）。
• ライブコマンドには Python 3.8 以降、requests、TRANSISTOR_API_KEY が必要です （Account ページ → API Access）。このスキルはサービスを起動しません。