Technical Specification

WhitePrint AudioEngine完全技術仕様書

5つのマイクロサービスで構成されるAI駆動オーディオマスタリングシステムのアーキテクチャ、API仕様、DSP信号処理チェーン、LLM統合ロジック、デプロイ構成の完全な技術リファレンス。

SYSTEM ARCHITECTURE

4段階パイプライン: Analysis → Deliberation → DSP Mastering → Output。全サービスはステートレスに設計され、Google Cloud Run上でスケーリングする。ファイルは処理後即時削除され、永続ストレージには一切保存されない。

Concertmaster

オーケストレーター (The Conductor)

Python 3.12 / FastAPI

パイプライン全体を制御する唯一の外部公開サービス。URL解決 → Audition → Deliberation → Rendition-DSP のフローを統括。

Endpoints

POST/api/v1/jobs/masterマスタリングジョブ投入 (4ルート: full / analyze_only / deliberation_only / dsp_only)

GET/healthヘルスチェック

Key Features

External: Authorization: Bearer wpk_... / Internal: X-Api-KeySSRF保護 (プライベートIP/メタデータサーバーブロック)URL自動変換 (Google Drive / Dropbox / OneDrive / Suno / SoundCloud / yt-dlp)httpx 非同期コネクションプールOIDC IDトークンによるサービス間認証

Audition

スコアリーダー (分析)

Python 3.12 / FastAPI / NumPy / SciPy

BS.1770-4準拠のラウドネス解析、9次元エンベロープ抽出、BPM/Key推定、Vertex AIによるセクション検出を実行。

Endpoints

POST/api/v1/analyzeURLからオーディオ分析

POST/api/v1/analyze/fileファイルパスから分析

GET/healthヘルスチェック

Key Features

K-weightingフィルター (ITU-R BS.1770-4)9次元時系列エンベロープ (LUFS/Crest/Width/Sub/Bass/Vocal/Brightness/LowMono/Transient)True Peak測定 (4x オーバーサンプリング)BPM推定 (onset_strength + autocorrelation)Key推定 (Chroma Energy Normalization Statistics)Vertex AI Structured Output によるマクロフォーム解析DSPフォールバック (Vertex AI 障害時)

Deliberation

TRIVIUM 3-Sage 合議エンジン

Python 3.12 / FastAPI

3つの独立AIエージェント (Grammatica/Logica/Rhetorica) が並列でDSPパラメータを提案し、加重中央値マージで最適値を決定。

Endpoints

POST/api/v1/deliberate3-Sage合議実行

GET/healthヘルスチェック

Key Features

OpenAI / Anthropic / Vertex AI 3プロバイダー同時活用加重中央値マージ (confidence × valid_param_ratio)3段JSON正規化 (strict → lenient → regex)マルチキーローテーション (API障害耐性)セクション別オーバーライド (section_overrides)12 Agents JP / TSE プラグインアーキテクチャ

Rendition-DSP

マスタリングエンジン

Python 3.12 / FastAPI / NumPy / SciPy

14段アナログモデリングDSPチェーンによるマスタリング処理。3パス収束ループ、LR8クロスオーバー4バンド圧縮、TPリミッター搭載。

Endpoints

POST/api/v1/masterURLからマスタリング

POST/api/v1/master/fileファイルパスからマスタリング

GET/healthヘルスチェック

Key Features

14段DSPチェーン (Input Gain → EQ → M/S → Saturation → Comp → Limiter → Dither)3パス収束ループ (ラウドネス正規化)LR8 (48dB/oct) クロスオーバー 4バンド圧縮Koren真空管モデル (Triode)4x オーバーサンプル True Peak リミッター v3HP-TPDF ディザ (16bit出力時)セクション別自動化 (section_overrides)GCS FUSE / /tmp フォールバック

UI

フロントエンド

Next.js 15.5 / React 19 / Tailwind CSS 4

マスタリングダッシュボード、A/B比較プレーヤー、分析ビジュアライゼーション、ユーザー認証、課金管理を提供。

Endpoints

POST/api/masterConcertmasterへのプロキシ

POST/api/uploadGCSへのファイルアップロード

POST/api/checkout決済 (NOWPayments)

Key Features

Supabase SSR認証ミドルウェア7段階FSMによるUI状態管理Vercel 4.5MB制限回避 (Supabase Storage経由)A/B比較プレーヤージョブ履歴管理 (Supabase)

14-STAGE DSP MASTERING CHAIN

Pure Python (NumPy/SciPy) 実装のアナログモデリングマスタリングチェーン。 3パス収束ループにより、ターゲットLUFSへの正確な到達を保証する。セクション別自動化 (section_overrides) により、楽曲構造に応じた動的パラメータ適用が可能。

Input Gain

input_gain_db

DAW出力レベル正規化

Range: -12 ~ +12 dB

4-Band Parametric EQ

eq_*_gain_db

Low Shelf (80Hz) / Low-Mid (300Hz) / High-Mid (3kHz) / High Shelf (10kHz)

Range: -6 ~ +6 dB

M/S Matrix (Encode)

ステレオ→M/S変換

M/S Processing

ms_*_gain_db

Mid低域ブースト / Side高域ブースト

Range: -6 ~ +6 dB

Transformer Saturation

transformer_*

ソフトクリッピング + 偶数次倍音

Range: 0.0 ~ 1.0

Triode Tube Saturation

triode_*

Koren真空管モデル: V_out = sign(x) × ln(1 + drive × |x + bias|)

Range: 0.0 ~ 1.0

Tape Saturation

tape_*

テープヒステリシスモデル: tanh(saturation × x)

Range: 0.0 ~ 1.0

M/S Matrix (Decode)

M/S→ステレオ復元

Dynamic EQ

dyn_eq_enabled

ハーシュネス抑制 (3kHz帯検出)

Range: 0 or 1

4-Band Crossover Compression

comp_*

LR8 (48dB/oct) 分離、バンド別圧縮: Sub/Bass/Mid/High

Range: variable

Stereo Enhancement

stereo_*

低域モノ化 + 高域ワイド化 + 全帯域幅制御

Range: 0.0 ~ 2.0

Parallel Compression

parallel_wet

ヘビー圧縮の Wet/Dry ブレンド

Range: 0.0 ~ 0.5

True Peak Limiter v3

limiter_ceil_db

4x オーバーサンプル + ルックアヘッド + 3パス収束

Range: -3.0 ~ -0.1 dBTP

HP-TPDF Dither

24bit→16bit時のみ。高域整形三角確率密度関数ディザ

24 DSP PARAMETERS

Deliberationエンジンが決定し、Rendition-DSPに渡される全24パラメータの完全仕様。

Parameter	Min	Max	Default	Unit
`input_gain_db`	-12	12	0	dB
`eq_low_shelf_gain_db`	-6	6	0	dB
`eq_low_mid_gain_db`	-6	6	0	dB
`eq_high_mid_gain_db`	-6	6	0	dB
`eq_high_shelf_gain_db`	-6	6	0	dB
`ms_side_high_gain_db`	-6	6	0	dB
`ms_mid_low_gain_db`	-6	6	0	dB
`comp_threshold_db`	-40	-6	-18	dB
`comp_ratio`	1	8	2.5	:1
`comp_attack_sec`	0.001	0.1	0.01	sec
`comp_release_sec`	0.05	1	0.15	sec
`limiter_ceil_db`	-3	-0.1	-1	dBTP
`transformer_saturation`	0	1	0	—
`transformer_mix`	0	1	0	—
`triode_drive`	0	1	0	—
`triode_bias`	0	1	0	—
`triode_mix`	0	1	0	—
`tape_saturation`	0	1	0	—
`tape_mix`	0	1	0	—
`dyn_eq_enabled`	0	1	0	bool
`stereo_low_mono`	0	1	0	—
`stereo_high_wide`	0	2	1	—
`stereo_width`	0	2	1	—
`parallel_wet`	0	0.5	0	—

BS.1770-4 ANALYSIS METRICS

Auditionサービスが算出する全16メトリクスの仕様。

integrated_lufs

BS.1770-4 統合ラウドネス

LUFS

true_peak_dbtp

4x OS True Peak

dBTP

lra_lu

Loudness Range

psr_db

Peak-to-Short-term Ratio

crest_db

クレストファクター

stereo_width

Side/Mid エネルギー比

stereo_correlation

L/R クロスコリレーション

low_mono_correlation_below_120hz

120Hz以下位相相関

harshness_risk

2-6kHz ピーク比率

mud_risk

200-500Hz 平坦度指標

sub_ratio

20-60Hz エネルギー比

bass_ratio

60-250Hz エネルギー比

low_mid_ratio

250-500Hz エネルギー比

mid_ratio

500-2kHz エネルギー比

high_ratio

2k-8kHz エネルギー比

air_ratio

8k-20kHz エネルギー比

TRIVIUM 3-SAGE ARCHITECTURE

3つの独立AIエージェントが異なるプロバイダーで並列実行し、加重中央値マージにより最適なDSPパラメータを決定する。

Grammatica

ProviderOpenAI

Modelgpt-4o

構造と形式に注目。EQ/コンプの適正値に重点。

Logica

ProviderAnthropic

Modelclaude-sonnet-4-20250514

論理的整合性に注目。動的一貫性と位相整合。

Rhetorica

ProviderGoogle

Modelgemini-2.5-flash

表現力と感性。サチュレーション/ステレオ幅。

加重中央値マージ (Weighted Median Merge)

各Sageの提案値を confidence × valid_param_ratio で重み付けし、24パラメータそれぞれについて加重中央値を算出。セクションオーバーライドは全Sageの提案を統合し、時間軸上でマージ。

Strategy

weighted_median_merge

Output

24 params + sections

Timeout

180s

Fallback

デフォルト値

PIPELINE ROUTES

full

Pipeline: URL解決 → 分析 → 合議 → DSPマスタリング → WAV出力

Output: audio/wav + メトリクスJSON

Use Case: エンドツーエンドの自動マスタリング

analyze_only

Pipeline: URL解決 → 分析

Output: AnalysisResult JSON

Use Case: ラウドネス分析のみ実行

deliberation_only

Pipeline: URL解決 → 分析 → 合議

Output: DeliberationOutput JSON

Use Case: AIパラメータ提案の確認

dsp_only

Pipeline: URL解決 → DSPマスタリング (manual_params必須)

Output: audio/wav + メトリクスJSON

Use Case: 手動パラメータでのマスタリング

INFRASTRUCTURE

Compute

Google Cloud Run (gen2)

Concertmaster: 2vCPU/4GiB, Rendition-DSP: 4vCPU/8GiB

Storage

Google Cloud Storage

GCS FUSE マウント + /tmp フォールバック

Auth

Supabase Auth (SSR)

Email/Password + OAuth (Google)

Database

Supabase PostgreSQL

jobs / billing / users テーブル

Frontend

Cloud Run (standalone)

Next.js 15.5 / Dockerfile / standalone output

CI/CD

Cloud Build

cloudbuild.yaml → Docker → Cloud Run deploy

SECURITY

SSRFvalidate_url_safe() — プライベートIP/メタデータサーバー/ループバックアドレスをDNS解決後にブロック

APIキー漏洩CONCERTMASTER_API_KEY はサーバーサイド環境変数のみ。NEXT_PUBLIC_ 接頭辞禁止

サービス間なりすましOIDC IDトークン認証 (Google Cloud IAM)

ファイルサイズ攻撃Upload: 200MB / Concertmaster: 200MB / 44Bバイト最小チェック

XSSReact自動エスケープ + CSP headers

認証バイパスSupabase SSRミドルウェア — /app/history, /app/settings 保護

LLM出力ハルシネーション3段JSON正規化層 + パラメータ範囲クランプ

WhitePrint AudioEngine Technical Specification v1.0 — Last updated: 2026-04-15