DeviceRec

A device controller is passed a handle to a DeviceRec with every selector. Yes, we know, it’s a monster.

typedef struct {
  PrMemoryHandle        deviceData;
  short                 command;
  short                 mode;
  csSDK_int32           timecode;
  short                 timeformat;
  short                 timerate;
  csSDK_int32           features;
  short                 error;
  short                 preroll;
  CallBackPtr           callback;
  PauseProcPtr          PauseProc;
  ResumeProcPtr         ResumeProc
  long                  xtimecode;
  long                  keycode;
  short                 editmode;
  short                 exteditmode;
  Print2TapeProcPtr     PrintProc;
  HWND                  parentWindow;
  piSuitesPtr           piSuites;
  char*                 displayName;
  TimecodeUpdatePtr     TimecodeUpdateProc;
  void*                 classID;
  long                  version;
  short                 videoStreamIsDrop;
  short                 autoDetectDropness;
  char*                 currentDeviceIDStr;
  long                  preferredScale;
  unsigned long         preferredSampleSize;
  DroppedFrameCountPtr  DroppedFrameProc;
  csSDK_uint32          exportAudioChannels;
  csSDK_uint16          exportFlags;
  csSDK_int32           delayFrames;
} DeviceRec, *DevicePtr, \*\*DeviceHand;

deviceData

Handle to private data allocated during dsInit or dsRestart.

Saved in the application preferences, and restored when the app is restarted.

command

The command to be performed when you receive dsExecute.

mode

Used in three ways. For dsExecute/cmdNewMode, mode contains your device’s new mode.

For dsExecute/cmdStatus, mode is where you indicate the device’s current mode (the last mode reported will still be there).

For dsExecute/cmdShuttle, mode contains the shuttle rate (-100 to 100).

timecode

Used three ways. For dsExecute/cmdGoto and dsExecute/cmdLocate, the timecode field indicates the timecode to which your should move.

For dsExecute/cmdStatus, return the deck’s current timecode position via the timecode field, where:

  • kInvalidTimecode will display “N/A” (not available),

  • -2 will blank the timecode display, and

  • -3 will display “Searching…”.

For dsExecute/cmdJogTo, timecode specifies the location to which you should jog.

timeformat

Reports the format of timecode for a dsExecute/cmdStatus; 0 for non-drop frame, 1 for drop-frame.

timerate

Reports the frame rate of timecode for a dsExecute/cmdStatus call. Set to 24, 25, 30, or 60.

Note, for 23.976 fps footage, set timerate to 24, and timeformat to 1. 24 fps timecode will be used, as expected.

Of course, there is no such thing as 24 fps drop-frame timecode, but this was the way 23.976 fps support was added within the constraints of the existing API.

features

Reports the device’s features in response to a dsExecute/cmdGetFeatures call.

error

Set this field to an appropriate error code and return a non-zero value from your device controller.

preroll

Used by dsExecute/cmdLocate. Preroll is how far before (smaller timecode) the seek time specified in timecode you should seek.

The preroll value is the product of a calibration sequence the user performs.

callback

Pointer to a callback to use during dsExecute/cmdLocate to determine if the user is attempting to abort.

typedef csSDK_int32 (*CallBackPtr) (void);

If the return value is non-zero, the user has attempted to abort.

PauseProc

Pointer to a callback that you can use to temporarily pause any sequence grabber operations in a device-controlled window.

It is defined as follows:

typedef void (*PauseProcPtr) (void);

ResumeProc

A pointer to a routine to call to resume sequence capture after calling PauseProc.

Every call to PauseProc must be matched by a call to ResumeProc.

typedef void (*ResumeProcPtr) (void);

Call these routines before putting up an error alert, for instance:

(*(*theData)->PauseProc)();
// your error handler here
(*(*theData)->ResumeProc)();

If PauseProc isn’t called before putting up an alert (or any other dialog), video will be played over it

xtimecode

Duration of the movie being exported (used for the Export to Tape).

keycode

Unused.

editmode

Can be any combination of the following flags to enable user actions:

  • insertVideo,

  • insertAudio1,

  • insertAudio2,

  • insertTimeCode,

  • insertAssemble,

  • insertPreview

exteditmode

Unused.

PrintProc

New in 7.0, this callback is no longer needed as the host drives the Edit to Tape rather than the device controller.

A pointer to a plugin function Premiere calls to print to tape.

csSDK_int32 (*Print2TapeProcPtr)(
  PrMemoryHandle  deviceHand,
  long            selector);

deviceHand is passed to the plugin in DeviceRec. selector can be setupWaitProc, idle, or complete.

See cmdInsertEdit.

piSuites

Pointer to universal callback suites.

displayName

A 255 character string to display the name of the device the plugin is currently controlling.

TimecodeUpdateProc

During cmdLocate, use this to report timecode.

void (*TimecodeUpdatePtr)(
  csSDK_int32  outTimecode,
  void*        outClassID);

classID

Used for TimecodeUpdateProc

version

Premiere informs the device controller of the API version, so the plugin can modify it’s behavior to support multiple versions, if desired.

  • Premiere Pro CC, October 2013 update - kDeviceControlAPIVersion14

  • Premiere Pro CC, July 2013 update - kDeviceControlAPIVersion13

  • Premiere Pro CC - kDeviceControlAPIVersion12

  • Premiere Pro CS6.0.1 - kDeviceControlAPIVersion11

  • Premiere Pro CS5.5 - kDeviceControlAPIVersion105

  • Premiere Pro CS5 - kDeviceControlAPIVersion10

  • Premiere Pro CS3 and CS4 - kDeviceControlAPIVersion9

videoStreamIsDrop

If autoDetectDropness was set earlier, and the recorder called FormatChangedFunc to provide the drop-frame attribute of the timecode, 0Premiere will call cmdSetDropness and use this to tell the device controller if the video stream is drop-frame.

autoDetectDropness

Set this to true if you want Premiere to notify the device controller whether or not the video stream uses drop-frame timecode.

Premiere will get this timecode information from the active recorder.

The result will be sent during cmdSetDropness in videoStreamIsDrop.

currentDeviceIDStr

For internal use only.

preferredScale

The current timebase. Use this rather than calling piSuites->utilFuncs->getSettings(kSettingsProjectScale).

preferredSampleSize

New in Premiere Pro CS3. The current timebase. Use this rather than calling piSuites->utilFuncs->getSettings(kSetting sProjectSampleSize).

DroppedFrameProc

New in 7.0, if the Edit to Tape panel is supported, this callback is no longer needed as Abort on Dropped Frames is handled transparently to the device controller.

In Premiere Pro CS6.0.1, use this callback to query the current number of frames dropped during an insert edit.

A device controller can use this to provide the feature to abort an Edit to Tape if frames are dropped.

csSDK_int32 (*DroppedFrameProc)(
  void*  inClassID);

exportAudioChannels

New in 7.0. During cmdGetFeatures, the device controller should set the bits corresponding to the audio channels available on the device.

Then later during the record commands, if the device supports audio channel selection, the bits will be set by the host corresponding to audio channels to export: A1 == bit 0, A2 == bit 1, etc.

exportFlags

New in 7.0. During the record commands, one or more of the following may be set:

  • exportVideo - set if user has checked the Video checkbox in the Edit to Tape panel

  • processCCData - set if user has checked the Insert Closed Caption Data checkbox in the Edit to Tape panel

  • previewEdit - set if user has pressed the Preview button in the Edit to Tape panel

delayFrames

New in CC July 2013. If fCanDelayMovieStart was set, during an Edit to Tape, this will be the value as set by the user (in frames) in the Edit to Tape panel, and Premiere Pro will let the device controller handle the Delay Movie Start.