ElevenLabs オーディオ生成

.envにELEVENLABS_API_KEYが必要です。

テキスト音声変換

from elevenlabs.client import ElevenLabs
from elevenlabs import save, VoiceSettings
import os

client = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

audio = client.text_to_speech.convert(
    text="Welcome to my video!",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    voice_settings=VoiceSettings(
        stability=0.5,
        similarity_boost=0.75,
        style=0.5,
        speed=1.0
    )
)
save(audio, "voiceover.mp3")

モデル

モデル	品質	SSML対応	備考
eleven_multilingual_v2	最高の一貫性	なし	安定、本番環境対応、29言語
eleven_flash_v2_5	良好	<break>, <phoneme>	高速、一時停止/発音タグサポート
eleven_turbo_v2_5	良好	<break>, <phoneme>	最速のレイテンシ
eleven_v3	最も表現力豊か	なし	アルファ版 — 不安定、プロンプトエンジニアリング必須

選択: 信頼性にはmultilingual_v2、SSML制御にはflash/turbo、最大表現力にはv3（やり直し予定）。

スタイル別音声設定

スタイル	stability	similarity	style	speed
ナチュラル/プロフェッショナル	0.75-0.85	0.9	0.0-0.1	1.0
会話体	0.5-0.6	0.85	0.3-0.4	0.9-1.0
エネルギッシュ/YouTuber	0.3-0.5	0.75	0.5-0.7	1.0-1.1

セクション間の一時停止

flash/turboモデルの場合: SSMLブレークタグをインラインで使用します：

...section end. <break time="1.5s" /> Start of next...

1回の一時停止は最大3秒です。過度な一時停止は速度アーティファクトを引き起こす可能性があります。

multilingual_v2 / v3の場合: SSMLサポートなし。オプション：

• 段落区切り（空行） — 自然な0.3～0.5秒の一時停止を作成します
• ffmpegで後処理：オーディオを分割して無音を挿入します

警告: ...（楕円）は信頼できる一時停止ではありません — 単語/音として音声化される可能性があります。一時停止メカニズムとして楕円を使用しないでください。

発音制御

音声表記（すべてのモデル）: 単語を発音させたい方法で書きます：

• Janus → Jan-us
• nginx → engine-x
• ダッシュ、大文字、アポストロフィを使用して発音を誘導します

SSML音素タグ（flash/turboのみ）:

<phoneme alphabet="ipa" ph="ˈdʒeɪnəs">Janus</phoneme>

反復的なワークフロー

1. 生成 → リッスン → 発音/ペーシング問題を特定
2. 調整：音声表記、ブレークタグ、音声設定
3. 再生成。一時停止が十分に正確でない場合は、TTSエンジンと戦うのではなく、ffmpegで後処理に無音を追加してください。

ボイスクローニング

インスタントボイスクローン

with open("sample.mp3", "rb") as f:
    voice = client.voices.ivc.create(
        name="My Voice",
        files=[f],
        remove_background_noise=True
    )
print(f"Voice ID: {voice.voice_id}")

• client.voices.clone()ではなくclient.voices.ivc.create()を使用してください
• パスではなくファイルハンドルをバイナリモード（"rb"）で渡します
• m4aを先に変換：ffmpeg -i input.m4a -codec:a libmp3lame -qscale:a 2 output.mp3
• 複数のサンプル（2～3クリップ）で精度が向上します
• 音声IDを再利用用に保存します

プロフェッショナルボイスクローン: Creatorプラン以上が必要で、30分以上のオーディオが必要です。reference.mdを参照してください。

効果音

生成あたり最大22秒。

result = client.text_to_sound_effects.convert(
    text="Thunder rumbling followed by heavy rain",
    duration_seconds=10,
    prompt_influence=0.3
)
with open("thunder.mp3", "wb") as f:
    for chunk in result:
        f.write(chunk)

プロンプトのコツ: 「重い足音が木の床板の上を遅く意図的に、きしむ音を伴いながら」のように具体的にしてください

音楽生成

10秒から5分。client.music.generate()ではなくclient.music.compose()を使用してください。

result = client.music.compose(
    prompt="Upbeat indie rock, catchy guitar riff, energetic drums, travel vlog",
    music_length_ms=60000,
    force_instrumental=True
)
with open("music.mp3", "wb") as f:
    for chunk in result:
        f.write(chunk)

プロンプト構造: ジャンル、ムード、楽器、テンポ、ユースケース。背景音楽の場合は「no vocals」を追加するか、force_instrumental=Trueを使用してください。

Remotion統合

完全なワークフロー：スクリプトから同期シーンへ

VOICEOVER-SCRIPT.md → voiceover.py → public/audio/ → Remotion composition
        ↓                  ↓               ↓                 ↓
  シーンナレーション    シーンごとに    タイミング付き    <Audio>コンポーネント
  期間付き             MP3を生成       オーディオファイル  シーンと同期

ステップ1：シーンごとのオーディオ生成

ツールキットのボイスオーバーツールを使用して各シーンのオーディオを生成します：

# 各シーンのボイスオーバーファイルを生成
python tools/voiceover.py --scene-dir public/audio/scenes --json

# 出力:
# public/audio/scenes/
#   ├── scene-01-title.mp3
#   ├── scene-02-problem.mp3
#   ├── scene-03-solution.mp3
#   └── manifest.json  (各ファイルの期間)

manifest.jsonにはタイミング情報が含まれています：

{
  "scenes": [
    { "file": "scene-01-title.mp3", "duration": 4.2 },
    { "file": "scene-02-problem.mp3", "duration": 12.8 },
    { "file": "scene-03-solution.mp3", "duration": 15.3 }
  ],
  "totalDuration": 32.3
}

ステップ2：Remotionコンポジションでオーディオを使用

// src/Composition.tsx
import { Audio, staticFile, Series, useVideoConfig } from 'remotion';

// シーンコンポーネントをインポート
import { TitleSlide } from './scenes/TitleSlide';
import { ProblemSlide } from './scenes/ProblemSlide';
import { SolutionSlide } from './scenes/SolutionSlide';

// シーンの期間 (manifest.json から、30fpsで フレームに変換)
const SCENE_DURATIONS = {
  title: Math.ceil(4.2 * 30),      // 126 フレーム
  problem: Math.ceil(12.8 * 30),   // 384 フレーム
  solution: Math.ceil(15.3 * 30),  // 459 フレーム
};

export const MainComposition: React.FC = () => {
  return (
    <>
      {/* シーンシーケンス */}
      <Series>
        <Series.Sequence durationInFrames={SCENE_DURATIONS.title}>
          <TitleSlide />
        </Series.Sequence>
        <Series.Sequence durationInFrames={SCENE_DURATIONS.problem}>
          <ProblemSlide />
        </Series.Sequence>
        <Series.Sequence durationInFrames={SCENE_DURATIONS.solution}>
          <SolutionSlide />
        </Series.Sequence>
      </Series>

      {/* オーディオトラック - すべてのシーンを通して継続的に再生 */}
      <Audio src={staticFile('audio/voiceover.mp3')} volume={1} />

      {/* オプション：より低いボリュームの背景音楽 */}
      <Audio src={staticFile('audio/music.mp3')} volume={0.15} />
    </>
  );
};

ステップ3：シーンごとのオーディオ（代替案）

より細かい制御のため、各シーンに個別にオーディオを追加します：

// src/scenes/ProblemSlide.tsx
import { Audio, staticFile, useCurrentFrame } from 'remotion';

export const ProblemSlide: React.FC = () => {
  const frame = useCurrentFrame();

  return (
    <div style={{ /* スライドのスタイル */ }}>
      <h1>The Problem</h1>
      {/* シーンコンテンツ */}

      {/* このシーンが開始するときにオーディオが開始 (このシーケンスのフレーム 0) */}
      <Audio src={staticFile('audio/scenes/scene-02-problem.mp3')} />
    </div>
  );
};

音声オーバーへのビジュアルの同期

その逆ではなく、オーディオからシーンの期間を計算します：

// src/config/timing.ts
import manifest from '../../public/audio/scenes/manifest.json';

const FPS = 30;

// オーディオの期間をフレーム数に変換
export const sceneDurations = manifest.scenes.reduce((acc, scene) => {
  const name = scene.file.replace(/^scene-\d+-/, '').replace('.mp3', '');
  acc[name] = Math.ceil(scene.duration * FPS);
  return acc;
}, {} as Record<string, number>);

// コンポジションでの使用:
// <Series.Sequence durationInFrames={sceneDurations.title}>

オーディオタイミングパターン

import { Audio, Sequence, interpolate, useCurrentFrame } from 'remotion';

// オーディオフェードイン
export const FadeInAudio: React.FC<{ src: string; fadeFrames?: number }> = ({
  src,
  fadeFrames = 30
}) => {
  const frame = useCurrentFrame();
  const volume = interpolate(frame, [0, fadeFrames], [0, 1], {
    extrapolateRight: 'clamp',
  });
  return <Audio src={src} volume={volume} />;
};

// 遅延オーディオスタート
export const DelayedAudio: React.FC<{ src: string; delayFrames: number }> = ({
  src,
  delayFrames
}) => (
  <Sequence from={delayFrames}>
    <Audio src={src} />
  </Sequence>
);

// 使用例:
// <FadeInAudio src={staticFile('audio/music.mp3')} fadeFrames={60} />
// <DelayedAudio src={staticFile('audio/sfx/whoosh.mp3')} delayFrames={45} />

音声オーバー + デモビデオの同期

シーンに音声オーバーとデモビデオの両方がある場合：

import { Audio, OffthreadVideo, staticFile, useVideoConfig } from 'remotion';

export const DemoScene: React.FC = () => {
  const { durationInFrames, fps } = useVideoConfig();

  // 再生レートを計算してデモを音声オーバー期間に合わせる
  const demoDuration = 45; // 秒 (元のデモ長)
  const sceneDuration = durationInFrames / fps; // 秒 (音声オーバーから)
  const playbackRate = demoDuration / sceneDuration;

  return (
    <>
      <OffthreadVideo
        src={staticFile('demos/feature-demo.mp4')}
        playbackRate={playbackRate}
      />
      <Audio src={staticFile('audio/scenes/scene-04-demo.mp3')} />
    </>
  );
};

エラーハンドリング

import { Audio, staticFile, delayRender, continueRender } from 'remotion';
import { useEffect, useState } from 'react';

export const SafeAudio: React.FC<{ src: string }> = ({ src }) => {
  const [handle] = useState(() => delayRender());
  const [audioReady, setAudioReady] = useState(false);

  useEffect(() => {
    const audio = new window.Audio(src);
    audio.oncanplaythrough = () => {
      setAudioReady(true);
      continueRender(handle);
    };
    audio.onerror = () => {
      console.error(`Failed to load audio: ${src}`);
      continueRender(handle); // ハングするのではなくオーディオなしで続行
    };
  }, [src, handle]);

  if (!audioReady) return null;
  return <Audio src={src} />;
};

ツールキットコマンド: /generate-voiceover

/generate-voiceoverコマンドは完全なワークフローを処理します：

/generate-voiceover

1. VOICEOVER-SCRIPT.md を読み込み
2. 各シーンのナレーションを抽出
3. ElevenLabs APIでオーディオを生成
4. public/audio/scenes/ に保存
5. 期間を含むmanifest.jsonを作成
6. project.json をタイミング情報で更新

人気のある音声

• George: JBFqnCBsd6RMkjVDRZzb (温かいナレーター)
• Rachel: 21m00Tcm4TlvDq8ikWAM (クリアな女性)
• Adam: pNInz6obpgDQGcFmaJgB (プロフェッショナルな男性)

すべてリスト表示: client.voices.get_all()

完全なAPIドキュメントについては、reference.mdを参照してください。