動画と歌唱区間を分ける

一つのYouTube動画に複数の歌唱区間が登録されることがあります。このとき再生キューを動画IDだけで表すと、どの区間を選んだのかを区別できません。同じ動画を一つにまとめてしまえば、別々に選んだ区間が失われます。反対に、区間の開始・終了時刻を持ったまま順序を変えたり、任意の行から始めたりできないと、選択した区間へ移る手掛かりがなくなります。

実装資料のデータ構造を手がかりに、キューの選択処理を小さな独立サンプルへ切り出して確かめます。記事内の実行結果は、このサンプルを動かしたものです。

01 選ぶ歌唱区間の行動画ID・開始秒・終了秒
02 並べる再生キュー同じ動画の別区間も残す
03 決める現在の区間選んだ位置の項目を使う
公開画面で烏の行が選択され、ミニプレイヤーに同じ曲名と区間時刻が表示されている。
実画面の選択状態。音声の連続性や区間終端の自動遷移を検証した画面ではありません。

押す場所から試したい方はSheer Clipの画面付き操作ガイドをご覧ください。

実装で確認できた方式

確認できたソースでは、再生アイテムに動画IDとは別にstartSecondsとendSecondsを持たせています。キュー更新時にstartIndexから選択アイテムを解決し、shuffleが有効なら選択アイテムをキューの先頭へ置く実装でした。通常時はqueueの順番を保ち、currentIndex・currentItem・再生状態を更新します。

ソースに対応する単体テストは、アプリ本体の状態更新関数(reducer)を呼び出し、再生状態・queue件数・requestNonce、動画IDと開始・終了時刻の保持、3番目(index 2)を選んだときのcurrentItem/currentIndexを検査しています。テスト自身はreducer状態の補助検証と明記し、画面操作のE2E検証と区別しています。

この記事で動かすコードは本番からの完全転用ではなく、同じ考え方を説明するための記事用の独立サンプルです。特にサンプルは時刻や入力を検証しますが、本番の入力検証の仕様を再現したものではありません。

区間を保つための設計判断

例では、同じ動画に15〜38秒と72〜104秒の2区間があります。動画IDで重複を取り除くと、この2つを区別できません。そこで、区間をキューの1項目とし、動画IDは「どの動画を開くか」を示す値として残します。

表は横にスクロールできます。

判断することこのサンプルで選ぶ方法理由
同じ動画の別区間区間IDが異なる項目として残す動画IDによる重複除去で、選んだ区間を失わないため
再生する位置配列のstartIndexと、動画内のstartSecondsを分ける「3件目から」と「9秒から」は別の情報だから
時刻の引き継ぎ区間の開始・終了時刻を項目の中に保持並び順や現在位置を変えても、選んだ区間を参照できるため
入力の扱い空配列・範囲外の選択・終了が開始以下の区間は拒否このサンプルでは、有効な項目が選ばれることを前提にするため

また、items.slice()で配列を複製しているため、返されたキューの順番を変えても元配列の順番は変わりません。ただし各項目のオブジェクトは共有しています。後から項目の時刻そのものを書き換える設計にするなら、項目も複製するか、書き換えずに新しい項目を作る方針が必要です。

独立サンプルで確かめる

サンプルはアイテム配列と開始位置を受け取り、キュー、現在位置、現在アイテムを返します。まず各項目のID、動画ID、開始時刻・終了時刻を検査し、開始位置が配列範囲内の整数かも確認します。元の並びと各区間を保ち、同じ動画IDを持つ別区間も別のキュー項目として残すのが目的です。

以下はダウンロードできるsegment-queue.mjsの全内容です。テストファイルも同じフォルダへ保存すると、相対importのまま実行できます。

/**
 * A small, standalone model of selecting a singing segment for a play queue.
 * This is an article example, not production Sheer Clip code.
 */
export function makeSegmentQueue(items, startIndex = 0) {
  if (!Array.isArray(items) || items.length === 0) {
    throw new TypeError('items must be a non-empty array');
  }

  for (const item of items) {
    if (!item || typeof item.id !== 'string' || item.id.length === 0) {
      throw new TypeError('each segment needs an id');
    }
    if (typeof item.youtubeId !== 'string' || item.youtubeId.length === 0) {
      throw new TypeError('each segment needs a youtubeId');
    }
    if (!Number.isFinite(item.startSeconds) || item.startSeconds < 0) {
      throw new RangeError('startSeconds must be a non-negative finite number');
    }
    if (!Number.isFinite(item.endSeconds) || item.endSeconds <= item.startSeconds) {
      throw new RangeError('endSeconds must be greater than startSeconds');
    }
  }

  if (!Number.isInteger(startIndex) || startIndex < 0 || startIndex >= items.length) {
    throw new RangeError('startIndex must point to an item in the queue');
  }

  const queue = items.slice();
  return {
    queue,
    currentIndex: startIndex,
    currentItem: queue[startIndex],
  };
}

サンプルコード segment-queue.mjs を保存 テスト segment-queue.test.mjs を保存

関数を呼び出して、結果を表示する

実行例 segment-queue-demo.mjsも同じフォルダへ保存し、Node.js 24でnode segment-queue-demo.mjsを実行できます。動画への通信は行わず、選択したデータを表示します。

// Save alongside segment-queue.mjs, then run: node segment-queue-demo.mjs
import { makeSegmentQueue } from './segment-queue.mjs';

const segments = [
  { id: 'part-1', youtubeId: 'video-abc', startSeconds: 15, endSeconds: 38 },
  { id: 'part-2', youtubeId: 'video-abc', startSeconds: 72, endSeconds: 104 },
  { id: 'part-3', youtubeId: 'video-xyz', startSeconds: 9, endSeconds: 27 },
];

const result = makeSegmentQueue(segments, 2);
console.log(JSON.stringify({ count: result.queue.length, currentIndex: result.currentIndex, currentItem: result.currentItem }, null, 2));

入力例の動画IDは説明用の架空の値です。同じ動画video-abcから15〜38秒と72〜104秒の2区間、別動画video-xyzから9〜27秒を用意し、startIndex = 2を選びます。結果は次のとおりです。

currentIndex: 2
currentItem: { id: 'part-3', youtubeId: 'video-xyz', startSeconds: 9, endSeconds: 27 }

この結果は「3つ目の配列項目を選び、そのアイテムの区間時刻も残す」というサンプルの実行結果です。ブラウザで動画が9秒から再生されることを示すものではありません。

実行結果と再現手順

  1. 2つのファイルを同じフォルダに保存

    segment-queue.mjsとsegment-queue.test.mjsを一つの作業フォルダへ置きます。

  2. Node.jsの標準テストランナーで実行

    そのフォルダをカレントディレクトリにしてnode --test segment-queue.test.mjsを実行します。

  3. 4つの期待値を確認

    3番目を選ぶとindex 2になること、YouTube IDと時刻が保持されること、同じ動画IDの2区間が別アイテムとして残ること、空配列・範囲外index・長さ0以下の区間が拒否されることを確認します。

Node.js v24.19.0で、独立サンプルのテスト4件が成功しました。これはサンプルコードの実行結果であり、Sheer Clip本体のテスト一式を実行した結果ではありません。

自分の環境で試す

Node.js 24の作業フォルダへsegment-queue.mjs、segment-queue.test.mjs、segment-queue-demo.mjsを同じ場所へ保存し、node segment-queue-demo.mjsとnode --test segment-queue.test.mjsを実行します。例では3件・index 2・part-3が表示され、テスト4件が通ります。importエラーなら3ファイルの配置を、範囲エラーならstartIndexと終了秒を確認します。自分のキューでは動画IDではなく区間ごとのIDを使い、キュー位置と動画内の秒数を別の値として保持してください。これは状態モデルだけで、動画再生は検証しません。

この検証で分かること・残ること

サンプルで分かるのは、配列内のどの項目を現在選択するか、区間時刻を項目データとして保持できるか、同じ動画IDでも別区間を分けられるかという範囲です。YouTube IFrame APIの再生位置設定、再生終了時の区間境界検知、次の動画への自動遷移、ネットワーク状態や埋め込み可否は扱いません。

再生の連続性を確かめるには、テスト用動画の公開状態と埋め込み可否を揃えたブラウザ操作テストが別途必要です。

検証ソースと出典

参照した実装とテストのソーススナップショットはcommit 32c87bcc86913de8e404741a01b02817b2077fc6です。このスナップショットは確認日当日の公開版commit a9077c26a8d276f4081ab8b940572a14d63e8059と異なるため、同じコードがその公開版へそのまま含まれるとは確認していません。

  • apps/web/src/lib/player/types.ts:11-20 — PlaybackQueueItemの動画ID・区間時刻・sourceType。
  • apps/web/src/lib/player/playback-store.tsx:112-142 — REPLACE_QUEUEでの開始位置・current item・再生状態の更新。
  • tests/unit/video-timeline-segment-playback.test.ts:38-70,72-102,104-138 — キュー更新、区間フィールド保持、開始位置を検査するreducerテスト。

単体テストはソーススナップショットから読み取ったもので、今回の調査ではそのテストファイル自体を実行していません。ここに掲載したサンプルの4テストのみをローカル実行しました。