waveform optimization

Author: bea4dev

docs/docs/lib/media.md

@@ -20,6 +20,13 @@ You can trim the source in frames:
 <Video video="assets/demo.mp4" trim={{ from: 30, duration: 120 }} />
 ```
 
+Waveform display in the timeline is automatic for clips shorter than 60 seconds.
+For longer clips, set `showWaveform` to enable it explicitly:
+
+```tsx
+<Video video="assets/demo.mp4" showWaveform />
+```
+
 ### `video_length`
 
 Returns the length of a video in frames.
@@ -37,3 +44,10 @@ import { Sound } from "../src/lib/sound/sound"
 
 <Sound sound="assets/music.mp3" trim={{ trimStart: 30 }} />
 ```
+
+Waveform display in the timeline is automatic for clips shorter than 60 seconds.
+For longer clips, set `showWaveform` to enable it explicitly:
+
+```tsx
+<Sound sound="assets/music.mp3" showWaveform />
+```

docs/i18n/ja/docusaurus-plugin-content-docs/current/lib/media.md

@@ -20,6 +20,13 @@ import { Video } from "../src/lib/video/video"
 <Video video="assets/demo.mp4" trim={{ from: 30, duration: 120 }} />
 ```
 
+タイムラインの波形表示は60秒未満のクリップは自動で有効です。
+長いクリップは `showWaveform` を指定した場合のみ表示されます。
+
+```tsx
+<Video video="assets/demo.mp4" showWaveform />
+```
+
 ### `video_length`
 動画の長さを取得します。
 ```tsx
@@ -35,3 +42,10 @@ import { Sound } from "../src/lib/sound/sound"
 
 <Sound sound="assets/music.mp3" trim={{ trimStart: 30 }} />
 ```
+
+タイムラインの波形表示は60秒未満のクリップは自動で有効です。
+長いクリップは `showWaveform` を指定した場合のみ表示されます。
+
+```tsx
+<Sound sound="assets/music.mp3" showWaveform />
+```

src/lib/audio-plan.ts

@@ -39,6 +39,8 @@ export type AudioSegment = {
   fadeInFrames?: number
   fadeOutFrames?: number
   volume?: number
+  clipId?: string
+  showWaveform?: boolean
 }
 
 type Listener = () => void
@@ -79,7 +81,9 @@ export const registerAudioSegmentGlobal = (segment: AudioSegment) => {
     existing.durationFrames === segment.durationFrames &&
     (existing.fadeInFrames ?? 0) === (segment.fadeInFrames ?? 0) &&
     (existing.fadeOutFrames ?? 0) === (segment.fadeOutFrames ?? 0) &&
-    (existing.volume ?? 1) === (segment.volume ?? 1)
+    (existing.volume ?? 1) === (segment.volume ?? 1) &&
+    (existing.clipId ?? null) === (segment.clipId ?? null) &&
+    (existing.showWaveform ?? null) === (segment.showWaveform ?? null)
   ) {
     return
   }

src/lib/clip.tsx

@@ -147,6 +147,21 @@ export const useClipRange = () => {
   }, [start, end])
 }
 
+/**
+ * Returns the id of the current clip.
+ *
+ * 現在のクリップ ID を返します。
+ *
+ * @example
+ * ```ts
+ * const id = useClipId()
+ * ```
+ */
+export const useClipId = () => {
+  const ctx = useContext(ClipContext)
+  return ctx?.id ?? null
+}
+
 /**
  * Returns the nesting depth of the current clip.
  *

src/lib/sound/sound.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useId, useMemo, useRef } from "react"
 import { PROJECT_SETTINGS } from "../../../project/project"
 import { useGlobalCurrentFrame } from "../frame"
-import { useClipActive, useClipRange, useProvideClipDuration } from "../clip"
+import { useClipActive, useClipId, useClipRange, useProvideClipDuration } from "../clip"
 import { registerAudioSegmentGlobal, unregisterAudioSegmentGlobal } from "../audio-plan"
 import { fetchAudioBuffer } from "../audio"
 import { useIsPlaying, useIsRender } from "../studio-state"
@@ -38,6 +38,7 @@ export type SoundProps = {
   fadeInFrames?: number
   fadeOutFrames?: number
   volume?: number
+  showWaveform?: boolean
 }
 
 /**
@@ -123,8 +124,10 @@ export const Sound = ({
   fadeInFrames = 0,
   fadeOutFrames = 0,
   volume = 1,
+  showWaveform,
 }: SoundProps) => {
   const id = useId()
+  const clipId = useClipId()
   const clipRange = useClipRange()
   const isActive = useClipActive()
   const isPlaying = useIsPlaying()
@@ -297,25 +300,29 @@ export const Sound = ({
     registerAudioSegmentGlobal({
       id,
       source: { kind: "sound", path: resolvedSound.path },
+      clipId: clipId ?? undefined,
       projectStartFrame,
       sourceStartFrame: trimStartFrames,
       durationFrames: clamped,
       fadeInFrames: Math.min(fadeIn, clamped),
       fadeOutFrames: Math.min(fadeOut, clamped),
       volume: normalizedVolume,
+      showWaveform,
     })
 
     return () => {
       unregisterAudioSegmentGlobal(id)
     }
   }, [
     clipRange,
+    clipId,
     durationFrames,
     fadeInFrames,
     fadeOutFrames,
     id,
     normalizedVolume,
     resolvedSound.path,
+    showWaveform,
     trimStartFrames,
   ])
 

src/lib/video/video.tsx

@@ -3,7 +3,7 @@ import { useEffect, useId, useMemo, useRef } from "react";
 import { useCurrentFrame } from "../frame";
 import { PROJECT_SETTINGS } from "../../../project/project";
 import { useIsPlaying, useIsRender } from "../studio-state";
-import { useClipActive, useClipRange, useProvideClipDuration } from "../clip";
+import { useClipActive, useClipId, useClipRange, useProvideClipDuration } from "../clip";
 import { registerAudioSegmentGlobal, unregisterAudioSegmentGlobal } from "../audio-plan";
 import { VideoCanvasRender } from "./video-render";
 import type { Trim } from "../trim";
@@ -37,6 +37,7 @@ export type VideoProps = {
   video: Video | string
   style?: CSSProperties
   trim?: Trim
+  showWaveform?: boolean
 }
 
 /**
@@ -175,9 +176,10 @@ export type VideoResolvedTrimProps = {
  * <Video video="assets/demo.mp4" trim={{ from: 30, duration: 120 }} />
  * ```
  */
-export const Video = ({ video, style, trim }: VideoProps) => {
+export const Video = ({ video, style, trim, showWaveform }: VideoProps) => {
   const isRender = useIsRender()
   const id = useId()
+  const clipId = useClipId()
   const clipRange = useClipRange()
   const resolvedVideo = useMemo(() => normalizeVideo(video), [video])
   const resolvedStyle = useMemo(() => {
@@ -215,15 +217,17 @@ export const Video = ({ video, style, trim }: VideoProps) => {
     registerAudioSegmentGlobal({
       id,
       source: { kind: "video", path: resolvedVideo.path },
+      clipId: clipId ?? undefined,
       projectStartFrame,
       sourceStartFrame: trimStartFrames,
       durationFrames,
+      showWaveform,
     })
 
     return () => {
       unregisterAudioSegmentGlobal(id)
     }
-  }, [clipRange, id, rawDurationFrames, resolvedVideo.path, trimEndFrames, trimStartFrames])
+  }, [clipId, clipRange, id, rawDurationFrames, resolvedVideo.path, showWaveform, trimEndFrames, trimStartFrames])
 
   if (isRender) {
     return (

src/ui/timeline.tsx

@@ -71,6 +71,7 @@ export const TimelineUI = () => {
   const projectSettings = PROJECT_SETTINGS
   const { fps } = projectSettings
   const [zoom, setZoom] = useState(1)
+  const waveformAutoLimitFrames = Math.max(1, Math.round(fps * 60))
 
   const placedClips = useMemo(() => stackClipsIntoTracks(clips), [clips])
   const trackCount = Math.max(1, placedClips.reduce((max, clip) => Math.max(max, clip.trackIndex + 1), 0))
@@ -79,6 +80,14 @@ export const TimelineUI = () => {
     for (const clip of placedClips) {
       const segments: ClipWaveformSegment[] = []
       for (const segment of audioSegments) {
+        if (segment.clipId && segment.clipId !== clip.id) {
+          continue
+        }
+        const autoAllowed = segment.durationFrames < waveformAutoLimitFrames
+        const shouldShowWaveform = segment.showWaveform ?? autoAllowed
+        if (!shouldShowWaveform) {
+          continue
+        }
         const segStart = segment.projectStartFrame
         const segEnd = segStart + segment.durationFrames - 1
         if (segEnd < clip.start || segStart > clip.end) {
@@ -103,7 +112,7 @@ export const TimelineUI = () => {
       }
     }
     return map
-  }, [audioSegments, placedClips])
+  }, [audioSegments, placedClips, waveformAutoLimitFrames])
   const clipMap = useMemo(() => {
     const map = new Map<string, PositionedClip>()
     placedClips.forEach((c) => map.set(c.id, c))