Creating and Testing Scripts

While it is easy to create scripts, it’s a good idea to first spend some time planning exactly what you intend the script to do. Sometimes a single script can be designed to fit multiple situations, or it may be easier to create multiple similar scripts, with each configured for a specific case.

Creating a Script

Scripts can vary greatly. Simple scripts may contain only one or two commands, while complex scripts can contain many commands and dependencies on other scripts. No matter how complex the script, you create all scripts using the same basic methods.

To create a script
  1. Do one of the following:

    • Choose Project > Add to Project > Script, or press Command–Shift–Single Quote (’).

    • Control-click in the Outline or Graphical tab, choose Add from the shortcut menu, then choose Script from the submenu.

    • Click Add Script in the toolbar.

    A new script is added to the Outline and Graphical tabs.

  2. To name the script, do one of the following:

    • Enter the name in the Name field in the Script Inspector.

    • Select the script in the Outline or Graphical tab, click its name, type the new name, then press Return.

  3. Double-click the new script in the Outline or Graphical tab or click the Script tab to open the Script Editor.

  4. In the Script Editor, select the default Nop command line.

    The Script Command Inspector appears, displaying the command configuration display.

  5. Configure the command line as desired, and add new command lines as needed.

See Script Command Details for details on the commands you can add to a script. See About Connections for information on connecting scripts to your project’s elements.

Duplicating and Saving Scripts

Most scripts contain command lines that are specific to a particular function in a particular project. However, because it is often easier to modify an existing script rather than start from scratch, DVD Studio Pro includes several tools that allow you to create copies of a script for use in this and other projects.

Duplicating Scripts

When creating several similar scripts, use the Outline or Graphical tab’s duplication function to make a copy of a script.

To duplicate a script within a project
Do one of the following:
  • Select the script in the Outline or Graphical tab, then choose Edit > Duplicate.

  • In the Outline or Graphical tab, Control-click the script, then choose Duplicate from the shortcut menu.

A copy of the script is created with the same name as the original, with a number added to the end of the name.

Saving Scripts

You can save a script as an item description file, making it easy to import a script into other projects.

To save a script as an item description file
Do one of the following:
  • Select the script in the Outline or Graphical tab, then choose File > Export > Item Description.

  • Control-click the script in the Outline or Graphical tab, then choose Save Script from the shortcut menu.

Loading Scripts

You can load saved scripts into a DVD Studio Pro project.

To load a script file
Do one of the following:
  • Choose File > Import > Item Description to import a script item description (with an “.dspScript” extension).

  • Control-click in the Outline or Graphical tab, then choose Load Script from the shortcut menu.

The script appears in the Outline tab under the Scripts heading and as a new tile in the Graphical tab, and can now be edited as needed.

Testing Scripts

Once you have created a script, you will want to test it. Depending on the script’s function, you can test it with the Simulator, with the Apple DVD Player as part of an emulator test, or in set-top DVD players after you burn a disc.

Testing a Script in the Simulator

The DVD Studio Pro Simulator has a Registers display that shows useful information when testing a script. The display appears when you click the Simulator’s Info button.

Figure. Register section of the Simulator window showing SPRM values and controls.

You can display either the SPRM or GPRM values, or both at the same time. You can also choose whether the values appear as decimal numbers or hexadecimal numbers. Seeing the SPRM and GPRM values can be useful when you want to ensure the right values are being set in the registers.

Additionally, you are able to enter values into the registers to preset a specific condition you want to test. To enter a value, double-click its existing value and enter the new one. Also, you can name the GPRMs within the Simulator. To name a GPRM, double-click the existing name in the Description column and enter a new one.

The Simulator has several preferences settings that allow you to verify script commands that rely on general DVD player settings, such as language preferences, aspect ratio, and region code. See Simulator Preferences for more information on Simulator preferences.

See Simulating Your Project for more information on using the Simulator.

Testing a Script with DVD Player

The Apple DVD Player provides an additional way to test your scripts. Testing a project with DVD Player is referred to as emulating the project. It requires you to build the project, which creates the VIDEO_TS folder that DVD Player uses. See Emulating Your Project Using DVD Player for more information.

Testing a Script on Set-Top DVD Players

The best test to give your scripts is to play the title in a set-top DVD player. This method provides the most real-world experience, giving the scripts the most true tests.

To test scripts in a set-top player, you need to build and format your project, burning it onto a DVD. See Formatting Your Project for more information on burning a DVD.

General Scripting Information

There are a number of good practices to keep in mind when creating your scripts:

  • Plan your GPRM partitioning: Partitioning one or more of the eight 16-bit GPRM registers can add a lot of flexibility to your script writing by making many GPRM registers available to be used. However, keep in mind that some scripting configurations and display conditions require full 16-bit GPRM registers. Also, when you import a script item description, any GPRMs used by the script must be partitioned exactly the same as they were when the script was originally created. To ensure compatibility, it is a good idea to consistently partition your GPRMs the same way for each project. See General Purpose Register Memories for information on saving and loading GPRM configurations.
  • Don’t forget about display conditions: Menus, tracks, and stories can all have display conditions applied to them. Display conditions work a lot like a simple pre-script—they determine whether the element should play, and if not, provide a jump to an alternative element. One advantage of a display condition is that it is part of the track and is placed in the same video title set (VTS) file as the track—by default, all scripts are placed in VTS 1 (though you can move them to the track’s VTS with the VTS Editor). In some cases, there could be a slight delay as the DVD player jumps from one VTS to the other to run a script. An additional advantage is that a display condition executes whether you jump to an element’s root or to a part of it (such as a button or marker). See Pre-Scripts and Display Condition for more information.
  • There are many ways to do the same thing: When creating your script, you will often find that there are alternate ways to accomplish the same task. The simplest approach is often the best, but other considerations, such as a lack of available GPRMs, may force you to be creative in your script writing. Sometimes it is better to create several small scripts rather than one large one that covers all situations.
  • Make sure the script has a way to end: It is important for the script to have an exit point that terminates its running and returns to playing the disc. For example, if you run a script that only uses the set command to configure some registers, the DVD player will just sit and wait for the script to finish, which it never will.

    You create the exit point by using one of three commands: jump, resume, and exit pre-script. You can use a jump command in any script; however, you can use the resume and exit pre-script commands only in specific script types. See Script Command Details for more information on these commands.