Getting Started¶
Selector Calling Sequence¶
The best ways to get familiar with the recorder API is to observe the messages sent between Pre- miere and the recorder plug-in.
recmod_Startup8 is sent once when Premiere launches. When Project Settings > Capture Settings is opened, recmod_Open is sent to create a new recorder instance and open the capture driver. recmod_GetSetupInfo8 is then sent, so the recorder can specify which settings buttons (if any) should be enabled in the Capture Settings window when the recorder is selected.
If one or more settings buttons are enabled and then clicked by the user, recmod_ShowOptions is sent so the recorder can display a dialog (and save any user choices). When the Capture Settings window is closed, recmod_Close is sent to end the capture instance.
Whenever the Capture panel is open, the recorder will receive recmod_SetActive calls, with a parameter telling it to become active or inactive (based on user activity). recmod_SetDisp provides the plug-in the dimensions of the preview area in the Capture panel. recmod_Idle is repeatedly sent until the Record button is pushed, to give the recorder time to update the preview area and play audio coming from the capture hardware.
When the user clicks Record, or starts an In/Out or Batch capture, recmod_PrepRecord8 is sent. The recorder prepares to capture, and if a start timecode is provided, tells the device controller to get the device into position using preRollFunc. The preRollFunc will block until the device is exactly in the right position, and when it returns, the recorder should immediately return back to Premiere, open which recmod_StartRecord is then sent to the recorder, which should im- mediately starts capturing.
When the recorder starts capturing and returns from recmod_StartRecord, Premiere will repeatedly call recmod_ServiceRecord to give the recorder processor time. During recording, report status to Premiere with StatusDispFunc.
The capture may be stopped in several ways:
- The user could click the Stop button,
- the capture may reach the predetermined out point of an In/Out or Batch capture,
- or the recorder might return an error from
recmod_ServiceRecord.
In all cases, recmod_StopRecord will be sent to stop the capture, possibly followed by recmod_CloseRecord if there no more items in the batch.
Finally, recmod_Close is sent when the Capture panel is closed to destroy the recorder instance. recmod_Shutdown is sent when Premiere terminates.
Try the Sample Recorder Plug-in¶
Now that you’ve read the overview of the selector calling sequence above, build the sample re- corder plug-in included with this SDK, and give it a whirl. To properly simulate a capture, you’ll also need to create an .sdk media file and place it in the proper location.
- Build the recorder, importer, and exporter into the plug-ins directory
- Launch Premiere Pro and use the exporter to transcode any media file into the .sdk file format.
- Place the newly created media file at “C:premiere.sdk” on Windows, or “premiere.sdk” on the Desktop on Mac OS.
Now when you “capture” a file, it will use this file, and automatically import it using the importer.
Metadata¶
Pixel aspect ratio and timecode are provided by the recorder by filling out recCapturedFileInfo. Starting in CS4, after a clip has been captured, if Premiere has an XMP handler that supports the clip’s filetype, the XMP handler will open the captured file and inject the information. If no such XMP handler is provided, the recorder is responsible for embedding any pixel aspect ratio information to the file, but Premiere will send imSetTimeInfo8 to the importer to stamp the file with timecode.
Save Captured File Dialog¶
After a single clip is captured, the Save Captured File dialog allows the user to rename the filename of the clip just captured. The recorder is not involved in this process. Instead, the importer is called to open the newly captured clip, and it is sent imSaveFile8 with the move flag set to true to move the file. This is handled by the importer, since imSaveFile8 is usually already implement- ed to support the Project Manager.
Switching Preview Area Between Different Frame Sizes¶
FormatChangedFunc enables recorders to tell Premiere when the pixel aspect ratio has changed so the Capture Panel preview area can be resized. It can be called during preview, and even during capture.
Scene Detection¶
A recorder can optionally implement one or both of two features based on scene detection: Scene Capture and Scene Searching. What determines a scene break is up to the discretion of the re- corder. The built-in DV recorder determines scene breaks by time/date breaks in the DV stream. But a recorder could analyze the video for breaks, or use any method it chooses to implement.
Scene Capture¶
Scene Capture enables a recorder to capture a continuous stream to multiple files divided up by scenes.
To support scene capture, the recorder must set recInfoRec8.canCaptureScenes = kPrTrue during recmod_Startup8. When the user captures with Scene Detect on, recCapParmsRec8.captureScenes will be non-zero during recmod_PrepRecord8. The recorder should begin capture, and when it detects the end of a scene, call SceneCapturedFunc8, to notify Premiere that a scene has been captured. Premiere passes back the recFileSpec8 to
give the recorder the filepath to which the next scene should be captured. Premiere also reserves memory for and passes back recCapturedFileInfo for the next capture.
Scene Searching¶
Scene Searching enables a recorder to fast forward or rewind to different scenes. The user can hit the Next Scene or Previous Scene buttons several times to seek several scenes away. Of course, this feature is only possible with the help of a device controller as well.
To support scene capture, the recorder must set recInfoRec8.canSearchScenes = kPrTrue during recmod_Startup8. When the user chooses Next Scene or Previous Scene, the recorder is sent recmod_StartSceneSearch. The scene searching algorithm happens in two passes.
The first pass is a play fast forward or backward in the initial direction. In this mode, when the recorder passes the scene boundary, it should call ReportSceneFunc to tell Premiere the approximate range where the scene boundary is and return rmEndOfScene. Premiere will call recmod_StopSceneSearch, followed by recmod_StartSceneSearch, to start a new slow scan scene search in the opposite direction, passing back the approximate range reported by ReportSceneFunc. When the recorder reaches the scene boundary again, it should once again call ReportSceneFunc and return rmEndOfScene.
Entry Point¶
Below is the entry point function prototype for all recorder plug-ins. Premiere calls this entry point function to drive the recorder based on user input.
int RecEntry (
csSDK_int32 selector,
rmStdParms *stdParms,
void *param1,
void *param2)
The selector is the action Premiere wants the recorder to perform. It tells the recorder the reason for the call.
stdParms provides the recorder with callback functions to access additional information from Premiere or to have Premiere perform tasks.
Parameters 1 and 2 contain state information and vary with the selector; they may contain a specific value or a pointer to a structure.
Return rmNoErr if successful, or an appropriate return code.
Standard Parameters¶
This structure is sent from Premiere to the plug-in with every selector.
typedef struct {
int rmInterfaceVer;
recCallbackFuncs *funcs;
piSuitesPtr piSuites;
} rmStdParms;
| Member | Description |
|---|---|
rmInterfaceVer |
Recorder API version
|
funcs |
Pointers to callbacks for recorders |
piSuites |
Pointer to universal callback suites |
Recorder-Specific Callbacks¶
Recorders have access to ClassData Functions and Memory Functions through the recCallbackFuncs, which is a member of rmStdParms.
StatusDispFunc, PrerollFunc, ReportSceneFunc, and SceneCapturedFunc8 are accessible through recCapParmsRec8, which is sent with recmod_PrepRecord8.
typedef struct {
ClassDataFuncsPtr classFuncs;
PlugMemoryFuncsPtr memoryFuncs;
} recCallbackFuncs;
int (*StatusDispFunc){
void *callbackID,
char *stattext,
int framenum};
csSDK_int32 (*PrerollFunc)( void *callbackID);
void (*ReportSceneFunc)(
void *callbackID,
csSDK_uint32 inSceneEdgeTimecode,
csSDK_uint32 inEarliestSceneEdgeTimecode,
csSDK_uint32 inGreatestSceneEdgeTimecode);
void (*SceneCapturedFunc8)(
void *callbackID,
prUTF16Char *inFileCaptured,
recFileSpec8 *outNextSceneFilename,
recCapturedFileInfo **outFileInfo);
void (*SceneCapturedFunc)(
void *callbackID,
char *inFileCaptured,
recFileSpec *outNextSceneFilename,
recCapturedFileInfo **outFileInfo);
void (*FormatChangedFunc)(
void *callbackID,
unsigned int inPixelAspectRatioNum,
unsigned int inPixelAspectRatioDen,
unsigned int inMaxFrameWidth,
unsigned int inMaxFrameHeight,
TDB_TimeRecord inFramerate,
int isDropFrame);
void (*GetDeviceTimecodeFunc)(
void *callbackID,
csSDK_uint32 *outTimecode,
TDB_TimeRecord *outFrameRate,
int *outIsDropFrame);
void (*AudioPeakDataFunc)(
void *callbackID,
recAudioPeakData *inAudioPeakData)
| Function | Description |
|---|---|
classFuncs |
See ClassData functions |
memoryFuncs |
Legacy memory-related callbacks. These are the same ones passed in through piSuites:. |
StatusDispFunc |
Available in recCapParmsRec8 during Callback function pointer for use during capture to call into Premiere and update status information in the Capture Window.
For example, 00;00;04;03 in NTSC drop-frame timecode would be represented as 123. |
PrerollFunc |
Available in Callback function pointer to initiate device control preroll, by sending a Callback returns when the deck is playing at the proper frame.
Host returns a |
ReportSceneFunc |
Although this callback is obsolete for Scene Capture (superceded by Available in The If it cannot, it marks the approximated timecode of the edge, and the If the scene break can be determined exactly, all three return parameters should be set to the same value. |
SceneCapturedFunc8 |
New in Premiere Pro 2.0. Available in Callback to notify Premiere that a scene has been captured. Premiere returns the recFileSpec8 to designate a filename for the next scene to capture and reserves memory for and returns |
SceneCapturedFunc |
Obsolete. Use SceneCapturedFunc8 above. |
FormatChangedFunc |
Available in recOpenParms during It can be called during preview, and even during capture. |
GetDeviceTimecodeFunc |
New in Premiere Pro CS3. Used to ask the device controller for its current timecode. |
AudioPeakDataFunc |
New in Premiere Pro CS5. Available in recOpenParms during The values will be updated as long as the capture panel is active or front. This call can be made from any thread, at any time. Metering can be provided for up to 16 channels, in any configuration desired: 1, 2, 4, 6/5.1, 8, or 16. The recorder provides the peak amplitude in The recorder can decide whether to pick a single value in In Premiere Pro’s built-in recorders, the long term peak data is currently buffered for 3 seconds at a time. If no new data is sent, it stays on the last value. So set the amplitude values to zero when finished. |