add_to_timeline
Add media clips to specific tracks and positions in Adobe Premiere Pro sequences, controlling placement with track index, timecode, and insert mode options.
Instructions
Adds a media clip from the project panel to a sequence timeline at a specific track and time.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sequenceId | Yes | The ID of the sequence (timeline) to add the clip to | |
| projectItemId | Yes | The ID of the project item (clip) to add | |
| trackIndex | Yes | The index of the video or audio track (0-based) | |
| time | Yes | The time in seconds where the clip should be placed on the timeline | |
| insertMode | No | Whether to overwrite existing content or insert and shift |
Implementation Reference
- src/tools/index.ts:144-153 (schema)Defines the tool metadata including name, description, and Zod input schema for validating parameters: sequenceId, projectItemId, trackIndex, time, and optional insertMode.
name: 'add_to_timeline', description: 'Adds a media clip from the project panel to a sequence timeline at a specific track and time.', inputSchema: z.object({ sequenceId: z.string().describe('The ID of the sequence (timeline) to add the clip to'), projectItemId: z.string().describe('The ID of the project item (clip) to add'), trackIndex: z.number().describe('The index of the video or audio track (0-based)'), time: z.number().describe('The time in seconds where the clip should be placed on the timeline'), insertMode: z.enum(['overwrite', 'insert']).optional().describe('Whether to overwrite existing content or insert and shift') }) }, - src/tools/index.ts:462-463 (registration)Registers the tool handler in the executeTool switch statement, mapping the tool name to the addToTimeline method call.
case 'add_to_timeline': return await this.addToTimeline(args.sequenceId, args.projectItemId, args.trackIndex, args.time, args.insertMode); - src/tools/index.ts:1001-1023 (handler)Tool handler wrapper in PremiereProTools class that calls the bridge method and formats success/error responses.
private async addToTimeline(sequenceId: string, projectItemId: string, trackIndex: number, time: number, insertMode = 'overwrite'): Promise<any> { try { const result = await this.bridge.addToTimeline(sequenceId, projectItemId, trackIndex, time); return { success: true, message: `Clip added to timeline successfully`, sequenceId: sequenceId, projectItemId: projectItemId, trackIndex: trackIndex, time: time, insertMode: insertMode, ...result }; } catch (error) { return { success: false, error: `Failed to add clip to timeline: ${error instanceof Error ? error.message : String(error)}`, sequenceId: sequenceId, projectItemId: projectItemId, trackIndex: trackIndex, time: time }; } - src/bridge/index.ts:268-289 (handler)Core handler in PremiereProBridge that generates and executes ExtendScript to insert the project item as a clip into the specified sequence track at the given time, returning clip details.
async addToTimeline(sequenceId: string, projectItemId: string, trackIndex: number, time: number): Promise<PremiereProClip> { const script = ` // Add item to timeline var sequence = app.project.getSequenceByID("${sequenceId}"); var projectItem = app.project.getProjectItemByID("${projectItemId}"); var track = sequence.videoTracks[${trackIndex}]; var clip = track.insertClip(projectItem, ${time}); // Return clip info JSON.stringify({ id: clip.clipID, name: clip.name, inPoint: clip.start, outPoint: clip.end, duration: clip.duration, mediaPath: clip.projectItem.getMediaPath() }); `; return await this.executeScript(script); }