The DaVinci Resolve Studio Scripting API provides a powerful gateway for users to automate, customize, and extend the functionality of this industry-leading post-production software. By leveraging scripting, users can move beyond manual operations and implement complex workflows, saving time and enhancing creative control. This documentation delves into the core aspects of the API, offering insights into its capabilities, usage, and potential applications for both novice and experienced scripters.
Understanding the Resolve Scripting Environment
DaVinci Resolve Studio supports user scripts written in both Lua and Python programming languages, mirroring the scripting capabilities found in Blackmagic Fusion. This dual language support ensures accessibility for a wide range of users, catering to those familiar with either scripting environment. Scripts can be executed in several ways: through the interactive Console window, via command line arguments, or by placing them in designated script directories.
The interactive Console window is an invaluable tool for quick experimentation and debugging. It allows for the immediate execution of simple scripting commands, enabling users to query or modify properties of DaVinci Resolve in real-time, and to test script snippets before integrating them into larger projects. For more automated or batch processing tasks, DaVinci Resolve can be launched in a headless mode without the user interface by using the -nogui command line option. This is particularly useful for rendering farms or for executing scripts on systems without direct user interaction.
Permissions for script execution can be managed within Resolve Preferences. Users can restrict script invocation to only the Console window or allow them to be invoked from the local network, offering flexibility in how scripts are deployed and accessed.
Script Placement and Accessibility
The location where you place your script files directly influences their availability within DaVinci Resolve. Scripts placed under the Utility folder will be listed and accessible from all pages within the application. For scripts intended for use specifically within the Fusion page, they should be placed under Comp or Tool folders. Alternatively, scripts can be organized into folders dedicated to individual pages such as Edit, Color, or Deliver, ensuring that they appear only within the relevant context, thereby streamlining the user interface and improving workflow organization.
The resolve Object: The Gateway to DaVinci Resolve
The resolve object serves as the fundamental starting point for all scripting interactions with DaVinci Resolve. It is the primary interface through which scripts can access and manipulate various aspects of the application, from project management to timeline editing and rendering. Many commonly used API functions are accessed through this central object.
For instance, to interact with the Fusion page, you would use the Fusion() function, which returns the Fusion object: Fusion() --> Fusion. This Fusion object then provides access to Fusion-specific scripting functionalities. Similarly, the OpenPage(pageName) function, a method of the resolve object, allows scripts to programmatically switch to a specified page within DaVinci Resolve, returning True if the page switch is successful. You can also ascertain the currently displayed page using GetCurrentPage() --> String.
Project Management and Workflow Automation
The resolve object offers a comprehensive suite of functions for managing DaVinci Resolve projects. Creating new projects is straightforward with CreateProject(projectName, mediaLocationPath) --> Project, which returns a Project object if the project name is unique, or None otherwise. Saving the current project is achieved with SaveProject() --> Bool. The API also facilitates the import and export of projects: ImportProject(filePath, projectName=None) --> Bool and ExportProject(projectName, filePath, withStillsAndLUTs=True) --> Bool. The latter allows for the inclusion of stills and LUTs in the export, a feature enabled by default. Restoring projects from a backup or archive is also supported via RestoreProject(filePath, projectName=None) --> Bool.
Folder management within the project structure is also scriptable. You can delete a specified folder using DeleteFolder(folderName) --> Bool if it exists.
Timeline Manipulation and Editing
Controlling and manipulating timelines is a core capability of the scripting API. The SetCurrentTimeline(timeline) function allows you to designate a specific timeline as the active one for the project. For editing operations, the AppendToTimeline(clip1, clip2, ...) function is crucial, enabling the appending of specified MediaPoolItem objects to the current timeline. This function can accept individual MediaPoolItem objects or an array of them. Furthermore, a more advanced version, AppendToTimeline([{clipInfo}, ...]) --> [TimelineItem], allows for detailed control over how clips are appended, including specifying start and end frames, media type, track index, and record frame. This detailed control is also available when importing media, with ImportMedia([{clipInfo}]) --> [MediaPoolItems] allowing the import of file paths with specific clip information.
The API also provides functionality for creating complex timeline structures. CreateCompoundClip([timelineItems], {clipInfo}) --> timelineItem allows for the creation of compound clips from a selection of timeline items, with optional parameters for setting the start timecode and name. Similarly, CreateFusionClip([timelineItems]) --> timelineItem enables the creation of Fusion clips.
Timeline tracks can be programmatically added and deleted. AddTrack(trackType, subTrackType) or AddTrack(trackType, newTrackOptions) allows for the addition of video, subtitle, or audio tracks, with various sub-track types supported for audio. DeleteTrack(trackType, trackIndex) removes tracks based on their type and index. Retrieving information about tracks is also possible with GetItemListInTrack(trackType, index) --> [items...] and GetTrackName(trackType, trackIndex) --> string, while SetTrackName(trackType, trackIndex, name) --> Bool allows for renaming tracks.
For managing media within the Media Pool, AddItemListToMediaPool(item1, item2, ...) and its array-based counterpart AddItemListToMediaPool([items...]) are used to add files or folders. A more sophisticated version, AddItemListToMediaPool([{itemInfo}, ...]), allows for adding items with specific frame ranges. The API also supports adding mattes to clips and timelines using AddClipMattesToMediaPool() and AddTimelineMattesToMediaPool(), respectively.
Color Grading and Node Management
The scripting API offers extensive control over color grading operations. The GetNodeGraph(layerIdx) function retrieves the node graph object for a clip at a specified layer index, returning the first layer if no index is provided. This allows for programmatic inspection and modification of the node structure. CopyGrades([tgtTimelineItems]) enables the copying of node stack layer grades to other timeline items, facilitating consistent grading across multiple clips.
The API also supports the management of stills and LUTs. GrabStill() captures a still from the current video clip, and GrabAllStills(stillFrameSource) can capture stills from all clips on a timeline. ExportLUT(exportType, path) allows for the programmatic export of LUTs from a clip.
Rendering and Export
Automating the rendering and export process is a key benefit of using the scripting API. AddRenderJob() adds a render job to the queue based on current render settings. SetRenderSettings({settings}) allows for the precise configuration of render parameters, while RenderWithQuickExport(preset_name, {param_dict}) initiates a quick export using a specified preset and parameters. The API can also retrieve available render resolutions for specific formats and codecs using GetRenderResolutions(format, codec). SetCurrentRenderMode(renderMode) allows for setting the active render mode.
Audio and Fairlight Integration
The scripting API extends its capabilities to the Fairlight audio post-production page. InsertAudioToCurrentTrackAtPlayhead(mediaPath, ...) allows for the insertion of audio media at the playhead position on a selected track. The API also supports audio transcription through TranscribeAudio() and clearing transcriptions with ClearTranscription(). For advanced audio processing, SetVoiceIsolationState(trackIndex, {VoiceIsolationState}) provides control over voice isolation parameters on audio tracks and individual timeline items.
Information regarding audio mapping can be retrieved using GetAudioMapping(). Furthermore, functions like AutoSyncAudio() facilitate the synchronization of audio with video clips.
Metadata and Marker Management
Managing metadata and markers is crucial for organizing and annotating media. The API allows for setting clip metadata using SetMetadata(metadataType, metadataValue) or a dictionary of metadata, and similarly for third-party metadata with SetThirdPartyMetadata(). Markers can be added to clips and timelines using AddMarker(frameId, color, name, note, duration), with options to update custom data via UpdateMarkerCustomData(frameId, customData) and delete markers by color using DeleteMarkersByColor(color). Flags can also be cleared using ClearFlags(color).
Fusion Page Specifics
Within the Fusion page, the Fusion() object provides access to Fusion-specific scripting. The Fusion() object allows you to get the current Fusion composition by index using GetFusionCompByIndex(compIndex).
Keyframe and Playback Control
The scripting API offers control over keyframe modes and playback. GetKeyframeMode() and SetKeyframeMode(keyframeMode) allow you to get and set the current keyframe mode.
Advanced Features and Utilities
The API includes several advanced features. DetectSceneCuts() can automatically detect scene cuts on a timeline. ConvertTimelineToStereo() and AnalyzeDolbyVision() provide tools for stereo conversion and Dolby Vision analysis, respectively. SmartReframe() enables intelligent reframing of footage.
For managing versions of clips, GetCurrentVersion() retrieves the current version name, and LoadVersionByName(versionName, versionType) allows for loading a specific named version. Stereo floating window parameters for both left and right eyes can be accessed via GetStereoLeftFloatingWindowParams() and GetStereoRightFloatingWindowParams().
The GetSetting(settingName) and SetSetting(settingName, settingValue) functions allow for reading and writing project-level settings. Similar functions, GetSetting(settingName) and SetSetting(settingName, settingValue), exist for timeline-specific settings.
The API also includes functions for managing burn-in presets, such as LoadBurnInPreset(presetName).
Extending Functionality: The Power of Scripting
The DaVinci Resolve Studio Scripting API is a powerful tool that unlocks a new level of control and automation for video professionals. By understanding and utilizing these functions, users can streamline complex tasks, develop custom workflows, and ultimately enhance their creative output. The ability to interact with DaVinci Resolve programmatically opens up possibilities for integrating with other software, creating bespoke tools, and pushing the boundaries of what is possible in post-production.