> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trimming Vs Timing

> VideoDB Editor uses two separate start parameters that control different aspects of video composition. Understanding these parameters is key to controlling what plays and when.

<a href="https://colab.research.google.com/github/video-db/videodb-cookbook/blob/main/editor/feature/trimming_vs_timing.ipynb" target="_blank">
  <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab" noZoom />
</a>

VideoDB Editor uses two separate "start" parameters that control different aspects of video composition. This trips up almost everyone at first - you set start=10 and expect the video to play 10 seconds into your timeline, but it actually just skips the first 10 seconds of the source video. Understanding these two parameters is key to controlling both what plays and when it plays.

## The Two Start Parameters

### `Asset.start` - Source Trimming

`VideoAsset(start=…)` skips the beginning of the source file.

<CodeGroup>
  ```python Python theme={null}
  asset = VideoAsset(
      id=video.id,
      start=10  # Skip first 10 seconds of source video
  )
  ```

  ```javascript Node.js theme={null}
  const asset = new VideoAsset(video.id, {
      start: 10  // Skip first 10 seconds of source video
  });
  ```
</CodeGroup>

<video controls width="100%">
  <source src="https://play.videodb.io/v1/e7aed706-0bcc-4756-b6e1-191a1b65a056.m3u8" type="application/x-mpegURL" />
</video>

This controls which part of your source material gets used. Think of it like fast-forwarding to a specific timestamp before hitting play - you’re extracting a segment from your original video.

### `track.add_clip(start=…)` - Timeline Positioning

Positions when the clip appears in the final timeline.

<CodeGroup>
  ```python Python theme={null}
  track.add_clip(
      start=5,  # Place clip at 5-second mark in final video
      clip=clip
  )
  ```

  ```javascript Node.js theme={null}
  track.addClip(
      5,    // Place clip at 5-second mark in final video
      clip
  );
  ```
</CodeGroup>

<video controls width="100%">
  <source src="https://play.videodb.io/v1/0b6c2017-7363-45d0-ae79-02f41bb7e0f8.m3u8" type="application/x-mpegURL" />
</video>

This controls when your clip plays in the composed output - like dragging a clip to a specific position on an editing timeline. It’s completely independent of what part of the source is playing.

## Key Concept: Independent Control

These parameters are completely independent, operating in two different coordinate systems.

`Asset.start` works in "source video time" (which part of the original file), while `track.add_clip(start=…)` works in "output timeline time" (when it appears in the final video).

You can extract any segment from your source and place it anywhere on your timeline.

<CodeGroup>
  ```python Python theme={null}
  # Extract seconds 10-20 from source, place at 5-second mark in timeline
  clip = Clip(
      asset=VideoAsset(id=video.id, start=10),  # TRIMMING: skip first 10s
      duration=10  # Play for 10 seconds
  )

  track = Track()
  track.add_clip(start=5, clip=clip)  # TIMING: appears at 5s in final
  ```

  ```javascript Node.js theme={null}
  // Extract seconds 10-20 from source, place at 5-second mark in timeline
  const clip = new Clip({
      asset: new VideoAsset(video.id, { start: 10 }),  // TRIMMING: skip first 10s
      duration: 10  // Play for 10 seconds
  });

  const track = new Track();
  track.addClip(5, clip);  // TIMING: appears at 5s in final
  ```
</CodeGroup>

<video controls width="100%">
  <source src="https://play.videodb.io/v1/44b2a5aa-21e0-4c5b-be31-a77a87d0c89d.m3u8" type="application/x-mpegURL" />
</video>

Timeline structure:

* 0-5 seconds: Blank (background color)
* 5-15 seconds: Video plays (showing seconds 10-20 from source)

## Asset Parameters

### `VideoAsset`

| Parameter | Type  | Description                                                             |
| :-------- | :---- | :---------------------------------------------------------------------- |
| id        | str   | Video ID from VideoDB collection                                        |
| start     | int   | Timestamp (seconds) where playback begins in source file. Default: `0`  |
| volume    | float | Audio volume multiplier. `1.0` = original, `0.0` = mute, `2.0` = double |
| crop      | Crop  | Crop edges of source video                                              |

### `AudioAsset`

| Parameter | Type  | Description                                              |
| :-------- | :---- | :------------------------------------------------------- |
| id        | str   | Audio ID from VideoDB collection                         |
| start     | int   | Timestamp (seconds) where playback begins in source file |
| volume    | float | Audio volume multiplier (`0.0` - `2.0`)                  |

## Common Patterns

### Sequential Clips (No Gaps)

<CodeGroup>
  ```python Python theme={null}
  # Clips play one after another
  track.add_clip(0, clip1)   # 0-10s
  track.add_clip(10, clip2)  # 10-20s
  track.add_clip(20, clip3)  # 20-30s
  ```

  ```javascript Node.js theme={null}
  // Clips play one after another
  track.addClip(0, clip1);   // 0-10s
  track.addClip(10, clip2);  // 10-20s
  track.addClip(20, clip3);  // 20-30s
  ```
</CodeGroup>

### Clips with Gaps

<CodeGroup>
  ```python Python theme={null}
  # Intentional pauses between clips
  track.add_clip(0, clip1)    # 0-10s
  track.add_clip(15, clip2)   # 15-25s (5s gap)
  track.add_clip(35, clip3)   # 35-45s (10s gap)
  ```

  ```javascript Node.js theme={null}
  // Intentional pauses between clips
  track.addClip(0, clip1);    // 0-10s
  track.addClip(15, clip2);   // 15-25s (5s gap)
  track.addClip(35, clip3);   // 35-45s (10s gap)
  ```
</CodeGroup>

### Overlapping Clips (Different Tracks)

<CodeGroup>
  ```python Python theme={null}
  main_track = Track()
  main_track.add_clip(0, main_clip)

  # Overlay appears at specific time
  overlay_track = Track()
  overlay_track.add_clip(20, overlay_clip)  # Appears at 20s

  timeline.add_track(main_track)
  timeline.add_track(overlay_track)
  ```

  ```javascript Node.js theme={null}
  const mainTrack = new Track();
  mainTrack.addClip(0, mainClip);

  // Overlay appears at specific time
  const overlayTrack = new Track();
  overlayTrack.addClip(20, overlayClip);  // Appears at 20s

  timeline.addTrack(mainTrack);
  timeline.addTrack(overlayTrack);
  ```
</CodeGroup>

## Complete Example

<CodeGroup>
  ```python Python theme={null}
  from videodb.editor import Timeline, Track, Clip, VideoAsset

  timeline = Timeline(conn)

  # Extract 15 seconds starting at 30s from source
  clip1 = Clip(
      asset=VideoAsset(
          id=video.id,
          start=30  # Skip first 30s of source
      ),
      duration=15  # Play for 15 seconds (shows 30s-45s of source)
  )

  track = Track()
  track.add_clip(start=10, clip=clip1)  # Place at 10s in final timeline

  timeline.add_track(track)
  stream_url = timeline.generate_stream()
  ```

  ```javascript Node.js theme={null}
  import { Timeline, Track, Clip, VideoAsset } from 'videodb';

  const timeline = new Timeline(conn);

  // Extract 15 seconds starting at 30s from source
  const clip1 = new Clip({
      asset: new VideoAsset(video.id, {
          start: 30  // Skip first 30s of source
      }),
      duration: 15  // Play for 15 seconds (shows 30s-45s of source)
  });

  const track = new Track();
  track.addClip(10, clip1);  // Place at 10s in final timeline

  timeline.addTrack(track);
  const streamUrl = await timeline.generateStream();
  ```
</CodeGroup>

Result: Final video has blank 0-10s, then shows seconds 30-45 from source at 10-25s position.

## Next Steps

<Card title="Trimming vs Timing" href="https://colab.research.google.com/github/video-db/videodb-cookbook/blob/main/editor/feature/trimming_vs_timing.ipynb" icon="book-open">
  Hands-on practice with trimming and timing patterns, multi-clip workflows, and timing precision.
</Card>