Blackmagic Forum

Note!
If you're using 18.5 Beta 3, all the functions listed below have been disabled.
In 18.5 Beta 4, the Timeline and MediaPool functions were enabled again and are now officially documented.

---

I had a look at the Resolve executable and found some API functions that aren't yet listed in the API documentation.

After some trial and error I was able to work out the parameters needed.

• Resolve
  
  • bool GetShowAllVideoFrames()
    
  • bool SetShowAllVideoFrames(bool enable)
    
  • bool GetSourceViewerMode()
    
  • bool SetSourceViewerMode(string mode)
    The modes I've been able to find so far are "source" and "multicam". I thought "audiotrack" would be there too but it's not.

• Project
  
  • int GetPlaybackSpeed()
    I don't know how this one works. I only tried it in the console where this command won't execute until playback is stopped. So mostly it returned 0 except for a single time when it returned 1.
    
    
  • timeline GetTimelineFromUniqueId(string uniqueId)
• Timeline
  
  • bool AddTrack(string trackType, string audioChannelSubType) Documented in v18.5
    
  • bool DeleteTrack(string trackType, int index) Documented in v18.5
    
  • bool SetTrackEnable(string trackType, int index, bool enable) Documented in v18.5
    
  • bool GetIsTrackEnabled(string trackType, int index) Documented in v18.5
    
  • bool SetTrackLock(string trackType, int index, bool lock) Documented in v18.5
    
  • bool GetIsTrackLocked(string trackType, int index) Documented in v18.5
    
  • bool SetClipsLinked(table items, bool link) Documented in v18.5
    
  • bool DeleteClips(table items) Documented in v18.5
• TimelineItem
  
  • bool GetClipEnabled() Documented in v18.5
    
  • bool SetClipEnabled(bool enable) Documented in v18.5
    
  • bool SetNodeLocked(int nodeIndex, bool lock)
    
  • bool ResetCurrentVersion()
    
  • bool ResetNode(int nodeIndex)
    
  • bool SetNodeActive(string nodeLabel)
• MediaPool
  
  • table TimelineItem AppendToTimeline(table clipInfo)
    In addition to the documented clipInfo properties; mediaPoolItem, startFrame, endFrame and mediaType, it also accepts trackIndex and recordFrame. This means we can finally place clips anywhere on the timeline! Documented in v18.5

It all seems to work just fine (except for where noted with newly discovered functions added later to this post), but since it's not documented you should probably expect changes in later releases.

Here's the same list in a similar form as the API readme (including the possible values for trackType and audioChannelSubType that I could find):

Code: Select all

Timeline
  AddTrack(trackType, audioChannelSubType)        --> Bool               # Adds a track of the given type ("audio", "video" or "subtitle") to the timeline. The audioChannelSubType is only needed for audio tracks and is one of "mono", "stereo", "5.1", "5.1film", "7.1", "7.1film", or "adaptive1" to "adaptive24".
  DeleteTrack(trackType, index)                   --> Bool               # Deletes a track of the given type at the specified index (int). 1 <= index <= GetTrackCount(trackType)
  SetTrackEnable(trackType, index, enable)        --> Bool               # Enables or disables the given track. The enable parameter is a boolean value.
  GetIsTrackEnabled(trackType, index)             --> Bool               # Returns whether a track is enabled or not.
  SetTrackLock(trackType, index, lock)            --> Bool               # Locks or unlocks the given track. The lock parameter is a boolean value.
  GetIsTrackLocked(trackType, index)              --> Bool               # Returns whether a track is locked or not.
  SetClipsLinked([items], link)                   --> Bool               # Links or unlinks the given clips (TimelineItem objects). The link parameter is a boolean value.

TimelineItem
  GetClipEnabled()                                --> Bool               # Returns whether a clip is enabled or not.
  SetClipEnabled(enable)                          --> Bool               # Enables or disables a clips. The enable parameter is a boolean value.
  SetNodeLocked(nodeIndex, lock)                  --> Bool               # Locks or unlocks a Color page node at the given nodeIndex (int). The lock parameter is a boolean value.

Updated for DaVinci Resolve 18.5

Very interesting!
Thanks for sharing.
By the way I was using your class browser the other day. It was a great help.
Cheers


Sent from my iPhone using Tapatalk

I'm glad you've found it useful!

This is awesome, thank you! Is there any chance you could explain how you found these functions? Or is it too complex to get into

Not complex at all, I just looked at the executable in a hex viewer. I searched for existing functions and next to them I found some that weren't documented.

roger.magnusson wrote:Not complex at all, I just looked at the executable in a hex viewer. I searched for existing functions and next to them I found some that weren't documented.

Great post - Thanks!

Have you found the function to set a track that clips will be added to? The equivalent to selecting V1/V2 etc.

Can you explain what executable you looked at here to search for functions?

I don't think they've added that yet.

On Windows the executable is %ProgramW6432%\Blackmagic Design\DaVinci Resolve\Resolve.exe.
On macOS it's /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/MacOS/Resolve.

Excellent. Thank you.

roger.magnusson wrote:I don't think they've added that yet.

That's a pity - but I'll keep digging.

I was hoping that because there is a SetTrackName() function to change the track name, that there may be a sister GetTrack() or SetTrack() function - but nothing!

It seems I flew too close to the sun.
In the Resolve 17 executable on Windows it's no longer possible to easily "spy" on which API functions are available by simply looking at the file.
On Windows...

You are a hero!
BTW, do you know the way to move a clip to the given start position in the timeline?

are the functions still available in v17?

Terry000 wrote:You are a hero!
BTW, do you know the way to move a clip to the given start position in the timeline?

Timeline editing/navigation through scripting isn't implemented yet. You can however create a new timeline from an EDL using MediaPool.ImportTimelineFromFile(filePath, {importOptions}). See details in the BMD documentation.

Terry000 wrote:are the functions still available in v17?

Yes, they worked in v17 the last time I checked, I think it was 17.2 or 17.3.

Mr. Magnusson you made my day!
Now I can start to script some procedure to synchronize the audio track selection between DVR and my midi controller.
The only thing that is still missing is a way to output the sound level of the selected track so I can fire up my level meter

In Resolve 18 I've found that you can no longer use "adaptive" for audioChannelSubType when adding an audio track.
bool AddTrack(string trackType, string audioChannelSubType)

You have to specify "adaptive1" up to "adaptive24" (or "mono", "stereo", "5.1film", "7.1film" like before).

I just added this to the first post.
table TimelineItem AppendToTimeline(table clipInfo)

In addition to the documented clipInfo properties; mediaPoolItem, startFrame, endFrame and mediaType, it also accepts trackIndex and recordFrame. This means we can finally place clips anywhere on the timeline!

Wow! Really?
Gonna have to try it…

Yes, it works!
This is awesome, good work Roger!
I found that it won’t add to a track that is occupied by a clip but you can add it to a track above it.

This opens so many possibilities.
First thing for me to do is to update my mixdown script.

Thanks again

MediaPool
table TimelineItem AppendToTimeline(table clipInfo)
In addition to the documented clipInfo properties; mediaPoolItem, startFrame, endFrame and mediaType, it also accepts trackIndex and recordFrame. This means we can finally place clips anywhere on the timeline!

Does this function also work on placing .exr files onto specific track and time?
I've tried this on .mov files and they worked fine. Somehow it did not do anything with .exr files...

I haven't tried it, but I would assume it should work as long as the EXR sequence is correctly imported as a clip to the media pool.

I previously posted that I was also stuck on EXRs. But I figured it out on my end. I actually just made a mistake previously which meant that I didn't get the MediaPoolItem itself but a list in which it was.

Anyone else who has issues: Besides the one deprecated function in the Add Subclips example, it is working with exrs too.

I'll post it here for easier access, I already changed the deprecated function to the current one.

Code: Select all

--[[
Example DaVinci Resolve script:
Adds subclips [frame 0 .. 23] to current timeline for all media pool root folder clips
--]]

resolve = Resolve()
projectManager = resolve:GetProjectManager()
project = projectManager:GetCurrentProject()
mediaPool = project:GetMediaPool()
rootFolder = mediaPool:GetRootFolder()
clips = rootFolder:GetClipList()

for clipIndex in pairs(clips) do
  clip = clips[clipIndex]
  videoCodec = clip:GetClipProperty()["Video Codec"]
  print(videoCodec)
  if videoCodec ~= "" then
    subClip = {}
    subClip["mediaPoolItem"] = clip
    subClip["startFrame"] = 0
    subClip["endFrame"] = 23

    if mediaPool:AppendToTimeline({ subClip }) then
      print("added subclip (first 24 frames) of \"" .. clip:GetName() .. "\" to current timeline.")
    end
  end
end



Roger, can you confirm if these functions work for Resolve 16 as well?

I have a client that just had to downgrade from v18 to v16 because of some bugs. And the scripts that were previously working now seem to be broken on these functions specifically:

AddTrack(string trackType, string audioChannelSubType)

TimelineItem AppendToTimeline(table clipInfo) >>specifically using the new arguments from the original post (trackIndex, recordFrame)

If they do work, do you have an example of how the syntax is different compared to v18?

Thank you!

(Apologies if this is a double post, I have another account for which posts never seem to go through)

AppendToTimeline using clipInfo was introduced with 16.2 according to the documentation. Before that you could only append using clip objects.

I suspect the same is true for AddTrack as I was using 16.2.1 when I found it.

Thank you!! Worked like a charm (I was on Resolve 16.0).

To echo the sentiment of many others on this thread, such a wildly helpful post. Really expands the scripting ability. Thanks for sharing.

jlewis_y wrote:Roger, can you confirm if these functions work for Resolve 16 as well?


(Apologies if this is a double post, I have another account for which posts never seem to go through)

Your other account doesn’t have your full real name so I delete the posts if the name isn’t updated.

This works

Code: Select all

                newClip = {
                    "mediaPoolItem" : mediaList[2],
                    "startFrame" : 1500,
                    "endFrame" : 2500,
                    "trackIndex" : 4,
                }
                mediaPool.AppendToTimeline( [newClip] )   


This don't work

Code: Select all

                newClip = {
                    "mediaPoolItem" : mediaList[2],
                    "startFrame" : 1500,
                    "endFrame" : 2500,
                    "trackIndex" : 4,
                    "recordFrame" : 12
                }
                mediaPool.AppendToTimeline( [newClip] )


Does anyone know why? I've tried many different versions of variables, all work until I insert "recordFrame" : XX or "recordFrame" : "XX"

I'm on DaVinci Resolve Studio v18.1 build 16

You need to take into account the start timecode of the timeline. For example, if it's a 25fps timeline starting at 01:00:00:00, the 13th frame would be 90012. You can get the start frame from the current timeline using timeline.GetStartFrame().

Code: Select all

newClip = {
    "mediaPoolItem" : mediaList[2],
    "startFrame" : 1500,
    "endFrame" : 2500,
    "trackIndex" : 4,
    "recordFrame" : 90012
}
mediaPool.AppendToTimeline( [newClip] )


Thanks!
This solved it. BTW, is it possible to set the starting timecode from the API?

The starting timecode of the timeline? Yes, using a timecode string, not frames.

Code: Select all

timeline.SetStartTimecode(timecode)

Some new toys to play with.

• Resolve
  
  • bool GetShowAllVideoFrames()
    
  • bool SetShowAllVideoFrames(bool enable)
    
  • bool GetSourceViewerMode()
    
  • bool SetSourceViewerMode(string mode)
    The modes I've been able to find so far are "source" and "multicam". I thought "audiotrack" would be there too but it's not.

• Project
  
  • int GetPlaybackSpeed()
    I don't know how this one works. I only tried it in the console where this command won't execute until playback is stopped. So mostly it returned 0 except for a single time when it returned 1.
    
    
  • timeline GetTimelineFromUniqueId(string uniqueId)
• Timeline
  
  • bool DeleteClips(table items)
• TimelineItem
  
  • bool ResetCurrentVersion()
    
  • bool ResetNode(int nodeIndex)
    
  • bool SetNodeActive(string nodeLabel)

We can scratch GetClipEnabled and SetClipEnabled off the list as those are now in the 18.5 Beta 1 scripting documentation.

While there are some more new documented functions in 18.5, I haven't found any undocumented functions that weren't already there in 18.

It was fun while it lasted but all of these functions are disabled in Resolve 18.5 Beta 3.

Oh man, all of them?!

Yes, unless I made some mistake. They're still there but they don't do anything and they don't return anything.

That’s a total bummer.

I'm nearly done with this complex script that's using the append to timeline (insert) on 18.1.3.

Guess I'm gonna have to wait till they officially release the update. Really, this should've been sorted out ages ago.

I wonder why these were undocumented in the first place and why are they now disabled. Some are quite useful and I have definitely used them since Roger has discovered them. I'd love to see them back in the API.

Ah damn. I created a script using an undocumented function. I assumed it could change at some point and I need to update my code but this just means I’ll avoid upgrading for now on my workstation. The script just saves too much time.
Hopefully they’ll get reintroduced soon and are no longer undocumented.

This time we were definitely flying to close to the sun, what a pity.
Now I need to check my scripts, because I am sure I used one or the other function.
Looks like I'll stay with DR17 forever.

Disappointed that BMD doesn't engage with this group of enthusiasts. Maybe there is a better place to discuss this with their development team? Anyone know?

God... I spent hours and hours on my script and was finally happy with it. Tuns of features that helped me edit a lot faster, even different profiles for different clients. Creating custom timecode sync etc... Now everything adds to the end of the timeline... What a shame. I must stay at DVR 18 or spend 2x or 3x editing time. I know it wasn't official, but it could have been added. Since it was just emulating the "Place on Top" function which already is on the speed editor and as a shortcut. I would love to see some new similar thing instead. But I don't think that API is a priority... Well, back to AHK scripting...

I would also love to see all these officially implemented, they are so useful!!

Yep, AppendToTimeline doesn’t work with trackIndex and recordFrame anymore. Hope this was a mistake by BMD and it gets reactivated in the official version or they implement a documented code like InsertToTimeline.

Thanks to the devs and people giving feedback many of the functions are back in 18.5 Beta 4.

All the Timeline and MediaPool functions are now documented in the BMD readme.

Hopefully some of the remaining useful functions can be re-enabled in the future. Like Project.GetTimelineFromUniqueId() and TimelineItem.SetNodeActive().

That’s fantastic news! Thank you so much for starting this thread in the first place!

Fantastic!
Thank you BMD team for officially bringing them back.

And thank you Roger as always.

It's great to have those back!

This is great news - indeed. Thanks a lot.

Yay! Thats so very cool!!! Excited to share what I've been cooking up!

@roger.magnusson Thanks for doing this and posting.
I just tested TimelineItem.ResetNode(int nodeIndex) in Resolve's WorkflowIntegrations API.
The method exists, but running as follows.. TimelineItem.ResetNode(1)

returns an error: Uncaught Error: ResetNode: Parse - Unknown object type detected for key:result (type:-1) at <anonymous>:1:23

Note: 'TimelineItem' is a confirmed timeline item, w/ 3 color nodes on it, and the first has LUT.

Does the ResetNode() method refer to Color nodes? or Fusion?

Curious if anyone has any insights. Thx.