VEGASPython

VEGASPython FAQ

This is an adaptation of the original VEGAS Scripting FAQ for VEGASPython

Section 1: General

What is VEGASPython Scripting?

When we speak of scripting in VEGAS, we're not referring to what may first come to mind for many of you, a written description of the scenes and dialog in a video production. Rather, we're referring to programmatic access to the internal data structures in VEGAS projects that allows you to automate things that you might normally do via the GUI. This may help you perform repetitive tasks, integrate with external applications, and implement customized features.

Which scripting languages does VEGAS use?

VEGAS uses the .NET framework to provide its scripting interface. VEGAS can execute C#, JScript, and Visual Basic script files directly. You do not need to compile them first. VEGAS can also execute scripts written in other .NET languages but those scripts must be compiled first.

Although JScript, Visual Basic, and C# can be easy to learn, it certainly helps to have programming experience before you try to write a VEGAS script.

Microsoft's developers' web site has more information about the .NET Framework and its various programming languages.

With the VEGASPython extension Vegas can now also execute Scripts programmed in Python.

Do I need to be a programmer to write scripts?

With VEGASPython and the possibility to use the Python Programing language for VEGAS scripting the hurdle for creating VEGAS scripts is getting much lower. Python is designed to be easy to learn and to use.

How do I create a script for VEGAS?

All Python scripts are plain text. You can use the interactive VEGASPython editor or any other text editor. If you want to debug longer scripts you can use the free version of Microsoft Visual Studio 2017 as editor and debugger. In the following we assume that you use the interactive VEGASPython editor if nothing else is defined.

How do I write a simple "hello world" script?

Enter the following text in the interactive VEGASPython editor:

print("hello world")

Click in the manu on „Execute Script“.

You will see in the output window the text „hello world“.

Very simple.

Remember the example provided in the original FAQ for C#

using System.Windows.Forms;
using ScriptPortal.Vegas;
 
public class EntryPoint {
    public void FromVegas(Vegas vegas) {
        MessageBox.Show("hello world");
    }
}

You see the difference ?

How do I use a script that has been posted on the web as a .txt file?

You can copy the entire contents of the script file from your browser window and paste it into a the interactive VEGASPython Editor. With „Save As“ you can specify the script file name. You can name it anything you want but make sure to name the file with the .py extension.

Do scripts pose a security risk to my computer?

Yes, scripts can be a security risk to your computer. A script run by VEGAS has the power to do almost anything: delete files, read files, write files, execute programs, access the Internet, access files on your local network, etc. You should always examine the contents of a script before running it and, if you don't understand what it is really doing, you should not run it unless it comes from a trusted source. In general, you should take the same precautions for scripts that you would take for any executable program you download.

How do I use my own or other .NET assemblies from within a script?

VEGASPython is based on IRONPython. IRONPython allows to easily access .NET assemblies in the Python script:

Here is an example for System.QWindows.Forms and ScriptPortal.Vegas.

import clr
clr.AddReference('System.Windows.Forms')
import System.Windows.Forms as WinForms
clr.AddReference('ScriptPortal.Vegas')
import ScriptPortal.Vegas as VEGAS
from ScriptPortal.Vegas import *

How do I use my own or other Python Modules from within a script?

In VEGASPython you can import Python modules using the standard Python syntax:

import sys
import os
from sys import *

As VEGASPython is based on IRONPython and on .NET it is not possible to import Python modules that are programmed using C. Most of the common modules are ported to IRONPython but some special modules may not work. Please check the IRONPython webpage for details.

Is there a way to determine the path of currently running script?

Yes, the filename including the complete path is available in the variable sys.argv. In Python sys.argv is a string list containing the script filename and all commandline arguments. The script filename is the first string in the list.

So if your script needs access to a helper file that resides in the same directory, your code might look like this:

clr.AddReference("System.IO") // we need System.IO for Path.GetDirectoryName and Path.Combine
import System.IO
from System.IO import *
import sys
scriptDirectory = Path.GetDirectoryName(sys.argv[0])
helperFile = Path.Combine(scriptDirectory, "HelperFile.ext")

How do I start a script from the commandline?

Pythonscripts can be started from the commandline together with VEGAS and commandline parameters can be passed to the script.

Example:

C:\Program Files\VEGAS\VEGAS Pro 16.0\vegas160.exe /SCRIPTARGS pythonscriptfilename /SCRIPTARGS arg1 /SCRIPTARGS arg2
  • pythonscriptfilename: path and filename of the pythonscriptfile to be executed
  • arg1: any text string as argument1
  • arg2: any text string as argument2

The number of arguments is not limited.

The first /SCRIPTARGS must be the script filename.

Example:

C:\Program Files\VEGAS\VEGAS Pro 16.0\vegas160.exe /SCRIPTARGS "D:\pythonfile\test.py" /SCRIPTARGS arg1 /SCRIPTARGS arg2

If the filename or a parameter include blanks, then the parameter must be enclosed in ´„„´. The pythonscript can access the commandline arguments as it is standard in Python via the variable sys.argv. This variable contains a list of strings with each argument as a separate string item in the list. The first item is the scriptfilename.

The python script:

for arg in sys.argv:
    print (arg)

gives as output:

[„D:\pythonfile\test.py“,“arg1“,„arg2“]

How do I add a script to the Scripting menu?

You can add a script to the Extension menu (under Vegas' Tools menu) by placing the script in one of the following directories:

  • C:\Users\<username>\Documents\Vegas Application Extensions\VEGASPYTHON\
  • C:\Users\<username>\AppData\Local\VEGAS Pro\14.0\Application Extensions\VEGASPYTHON\
  • C:\Users\<username>\AppData\Roaming\VEGAS Pro\14.0\Application Extensions\VEGASPYTHON\
  • C:\ProgramData\Vegas Pro\14.0\Application Extensions\VEGASPYTHON\
  • C:\Users\<username>\AppData\Local\Vegas Pro\Application Extensions\VEGASPYTHON\
  • C:\Users\<username>\AppData\Local\Vegas Pro\Application Extensions\VEGASPYTHON\
  • C:\ProgramData\Vegas Pro\Application Extensions\VEGASPYTHON\

You must use the subdirectoy VEGASPYTHON in the same directory where you installed the VEGASPYTHON.dll.

How do I add a script to the toolbar?

To add a script to the toolbar, first it must be located in the VEGASPython Scripting folders detailed above. Once added to the Extensionmenu, you can add a script to the toolbar using the 'Customize Toolbar' dialog in VEGAS' Options menu. The available scripts are listed at the bottom of of the available toolbar button list.

How do I assign a keyboard shortcut to a script?

To assign a keyboard shortcut to a script, first it must be located in the VEGASPython Scripting folders detailed above. Once added to the Extension menu, you can create a keyboard shortcut for the script using the 'Customize Keyboard' dialog in VEGAS' Options menu. The available scripts begin with the 'Script' keyword and are available under any context.

How do I make a custom icon appear for a script in the Scripting menu or toolbar?

You can make a custom icon appear for a script you've added to the Scripting menu or toolbar by placing a PNG image in the same folder that contains the script. The PNG file must have the same name as the script with the '.png' extension appended. For example, if the script is named „My Script.cs“, the toolbar image should be named „My Script.py.png“. The image must be 16 X 16 pixels and must have 32-bit color depth with an alpha channel for transparency.

How do I create and debug a script using a Visual Studio?

You can debug VEGASPython scripts usuing Microsoft Visual Studio 2017 as Editor and Debugger. You do not have to compile the script or do any fancy stuff. Please see the page debugging_of_scripts_with_visual_studio_2017

How do I print debug messages from my script?

You can print debug messages using the Python print() function. These messages are visible in the output window.

print("Debugmessage")

My question is not answered in the FAQ, where can I get more help?

The Scripting Forum is a good place to ask questions. The forum is frequently monitored by VEGAS staff and friendly VEGAS users who have considerable skills and experience. Questions posted in the forum occasionally make their way into this FAQ.

Where can I get updates to VEGASPython?

You can get the latest VEGASPython version here: VEGASPython

Section 2: Tracks and Events

How do I access the VEGAS attributes?

VEGASPython provides a variable pyVEGAS which is of the type VEGAS and provides the interface to all VEGAS internal data structures. You can find details of the data structures in the VEGAS Scripting API.

Example:

print (pyVEGAS.Version)

How do I find the currently selected track or event?

You can find the currently selected track or event by iterating through each track and event and examining the Selected property. The following functions provide an example of this:

def FindSelectedTrack(project):
    for track in project.Tracks):
        if track.Selected:
            return track
    return null;
 
print(FindSelectedTrack(pyVEGAS.Project))    
def FindSelectedEvents(project):
    selectedEvents = []
    for track in project.Tracks:
        for trackEvent in track.Events:
            if trackEvent.Selected:
                selectedEvents.Add(trackEvent)
    return selectedEvents
 
print(FindSelectedEvents(pyVEGAS.Project))

Note that multiple tracks and events can be selected at the same time. The first function returns only the first selected track while the second function returns all of the selected events. Events can be selected in tracks that are not selected.

How do I set the fade type (curve) for an event?

Every TrackEvent object has FadeIn and FadeOut properties which give you objects that control the event's ASR and (in the case of VideoEvents) transition effects. The Fade object has a Curve property which can be set to one of the CurveType enumeration values. The following example gives an event fade in curve the fast type.

evnt.FadeIn.Curve = CurveType.Fast

One tricky aspect of fades comes into play when two events overlap on the same track. In this case, only the trailing event's FadeIn really matters and, to designate the type of fade curve for the leading event, you actually must set the trailing event's ReciprocalCurve property. The following code snippet makes a slow curved fade transition between an event (trailingEvent) and any event on the same track that overlaps its leading edge:

trailingEvent.FadeIn.Curve = CurveType.Slow
trailingEvent.FadeIn.ReciprocalCurve = CurveType.Slow

How do I make a one second dissolve at the beginning and end of a video event?

You can add a dissolve (or any transition) to an event using its FadeIn and FadeOut properties. First you can set the length of the transition to the desired amount:

videoEvent.FadeIn.Length = Timecode.FromSeconds(1)

For video events, you can use a transition effect by creating a new instance of an Effect object using a transition PlugInNode then assign it to the Transition property of the appropriate Fade. To create a new transition effect, you must first find the appropriate PlugInNode. To find a transition node by name, use the GetChildByName method of the Transitions root node. The following function creates a new transition effect given its plug-in name:

def CreateTransitionEffect(plugInName):
    plugIn = pyVEGAS.Transitions.GetChildByName(plugInName)
    if plugIn==None:
        print("Failed to find plug-in:", plugInName)
    return Effect(plugIn)

Now you can set the event fade transitions and assign their preset:

Effect fadeInTx = CreateTransitionEffect("VEGAS Dissolve")
videoEvent.FadeIn.Transition = fadeInTx
fadeInTx.Preset = "Additive Dissolve"
Effect fadeOutTx = CreateTransitionEffect("VEGAS Slide")
videoEvent.FadeOut.Transition = fadeOutTx
fadeOutTx.Preset = "Additive Dissolve"

You must pass the full name of the plug-in to the GetChildByName method. The Plug-In Manager window shows the full name of each plug-in. Most built-in plug-ins begin with „VEGAS“.

How do I add media to the timeline?

You can use the OpenFile method of the VEGAS object to add a media file to the selected track at the current cursor position. The OpenFile method works much like the 'File.Open' menu command and will insert tracks if necessary. You can set the cursor position using the CursorPosition of the Vegas object's Transport property. The following method demonstrates how to insert a media file at a specific position on a specific track using the OpenFile method.

def InsertFileAt(fileName, trackIndex, cursorPosition):
    // first clear all track selections
    for track in pyVEGAS.Project.Tracks:
        track.Selected = false
    // select the desired track
    pyVegas.Project.Tracks[trackIndex].Selected = True
    // set the cursor position
    pyVEGAS.Transport.CursorPosition = cursorPosition
    pyVEGAS.OpenFile(fileName)

Sometimes you need more control of how you add media to the project. You can build events on the timeline by constructing media, tracks, events, and take objects individually:

def AddVideoEvent(mediaFile, start, length):
    media = Media(mediaFile)
    track = pyVegas.Project.AddVideoTrack()
    videoEvent = track.AddVideoEvent(start, length)
    take = videoEvent.AddTake(media.GetVideoStreamByIndex(0))
    return videoEvent

How do I add a text event to the timeline?

You can add a text event to the timeline by constructing a Media object from the text generator effect and adding the video event and take to the track.

def AddTextEvent(track, start, length):
    // find the text generator plug-in
    plugIn = pyVEGAS.Generators.GetChildByName("Titler")
    // create a media object with the generator plug-in
    media = Media(plugIn)
    // set the generator preset
    media.Generator.Preset = "centered"
    // add the video event
    videoEvent = track.AddVideoEvent(start, length)
    // add the take using the generated video stream
    take = videoEvent.AddTake(media.GetVideoStreamByIndex(0))
    return videoEvent

How do I make a script modify the text string in a text event?

You can't. Currently, one major shortcoming of the scripting API in VEGAS is that specific parameters of video effects are not accessible to scripts. The text string of text generators are one such parameter. Scripts can only set presets values for a given key frame.

How do I modify the pan/crop settings of a video event from a script?

Pan and crop settings can be manipulated using the VideoEvent's VideoMotion property. The VideoMotion object has a Keyframes collection that contains VideoMotionKeyframe objects. Each keyframe has a Position in time relative to the start of the event. Keyframes also have a Bounds polygon representing the four corners of the view-port onto the source media. The best way to manipulate this bounds rectangle is to use the keyframe's MoveBy, ScaleBy, and RotateBy methods. The keyframe's Center defines the point at the center of rotation.

The following function moves a video event into view from a position off screen over a two second period.

def PanFromLeft(VideoEvent videoEvent):
    // create a new keyframe at 2 seconds.
    key1 = VideoMotionKeyframe(Timecode.FromSeconds(2))
    // add the new keyframe
    videoEvent.VideoMotion.Keyframes.Add(key1)
    // get the first keyframe
    VideoMotionKeyframe key0 = videoEvent.VideoMotion.Keyframes[0]
    // get the width of the project
    videoWidth = pyVEGAS.Project.Video.Width
    // move the first keyframe just off screen
    key0.MoveBy(VideoMotionVertex(videoWidth, 0))

How do I set the opacity of a video track or event?

You can to set the CompositeLevel property of a VideoTrack object to effect the entire track's opacity trim level.

videoTrack.CompositeLevel = 0.5

You can also add a composite level envelope to the video track (described below) if you need to the opacity to change over time.

Individual event opacity can be set using the Gain property of the video event's FadeIn object:

videoEvent.FadeIn.Gain = 0.5

Section 3: Envelopes

How do I find a particular envelope for a given track or event?

To find an envelope by type, you can use the FindByType method of the appropriate Envelopes collection. Language: C#

pan = audioTrack.Envelopes.FindByType(EnvelopeType.Pan)

All Track objects (AudioTrack and VideoTrack) have an Envelopes collection. So do all BusTrack objects and VideoEvent objects. Envelopes collections also have a HasEnvelope method that allows you to quickly determine whether it contains an envelope of a particular type.

If you want to find an automation envelope on an audio track, you will need to find it by name. This means you need to iterate through the Envelopes collection and compare each envelope's name to the name you're looking for.

def FindEnvelopeByName(envelopes, envelopeName):
    for envelope in envelopes:
        if envelope.Name == envelopeName:
            return envelope
    return null;

Automation envelopes are named by both effect name and parameter name. For example an automation envelope for the delay parameter of the chorus effect is named „Chorus: Delay“.

How do I add an envelope to a track or event?

The first step to add an envelope to a track or event is to create a new envelope of the desired type. The Envelope class constructor can take any of the values in the EnvelopeType enumeration. The next step is to add the new envelope to the appropriate Envelopes collection.

volumeEnvelope = Envelope(EnvelopeType.Volume)
audioTrack.Envelopes.Add(volumeEnvelope)

In this case, audioTrack can be any audio track that does not already have a volume envelope. Certain envelope types can only be added to a specific context. For example, you cannot add a volume envelope to a video event. It is currently not possible for a script to add an audio effect automation envelope to an audio track or bus track.

How do I add points to an envelope?

You can add points to an envelope in much the same way you add envelopes to a track or event. The first step is to create an EnvelopePoint object then just add it to the envelope's Points collection.

envelopePoint = EnvelopePoint(Timecode.FromSeconds(1), 2.0, CurveType.Sharp)
envelope.Points.Add(envelopePoint)

The code fragment above creates a new envelope point positioned one second after the start of the envelope. The first argument to the EnvelopePoint constructor is its position. The position represents the point's x-coordinate on the timeline. The second argument is the envelope point's value at the given position. This value must lie somewhere between the envelope's Min and Max properties. Envelopes also have a Neutral property which defines the default or middle value for envelope points. The third argument is one of the CurveType enumeration values which represents how the curve following the point should ascend or descend to reach the next point in the envelope.

One rule to keep in mind when adding envelope points is that no two points can have the same position. An exception is thrown if you attempt to add a point with the same position as another. It is illegal to set a point's position to a negative value or, in the case of event envelopes, to a time beyond the end of the event. It is also illegal to set a point's value outside the envelope's min/max range.


Andere Sprachen
QR-Code
QR-Code en:vegas_python_faq (erstellt für aktuelle Seite)