These workflows create, copy, and modify video and audio clip nodes. For the most part, Wiretap handles audio clips and video clips in the same way. The main difference is how the clip format is defined.
The following classes are important in these workflows:
WireTapNodeHandleWireTapClipFormatWireTapAudioClipFormatThe following sections contain information regarding clip nodes and formats.
On an IFFFS Wiretap Server, a CLIP node is a container for child nodes of the following types.
| Node Type | Description |
|---|---|
| HIRES | Represents high-resolution video media. |
| ALPHA_HIRES | Represents the alpha of the high-resolution video media. |
| LOWRES | Represents low-resolution video media. Wiretap supports the use of low-resolution proxy versions of video media to increase the speed at which video clips are transferred and displayed. |
| ALPHA_LOWRES | Represents low-resolution alpha of the video media. |
| SLATE | Represents the lowest resolution video media available. If a LOWRES node exists, the SLATE node will be equivalent to the LOWRES node, and otherwise the SLATE node will be equivalent to the hires node. |
| AUDIOSTREAM | Represents an audio clip. |
| VERSION | Represents a version, in the context of multi-version clips. One VERSION node for each version. |
For video, the parent CLIP node is normally a shortcut to the HIRES node. A video clip node has at least two child nodes: the HIRES and SLATE nodes. It may also have a LOWRES child node if the clip has proxies. The resolution of a video clip node is stored in its metadata. The proxy version of a clip is stored on the Wiretap server like the high-resolution original.
An audio clip consists of a CLIP node (with zero frames) with an AUDIOSTREAM child node.
On the Wiretap Gateway server, a CLIP node is a container for child nodes of the following types.
| Node Type | Description |
|---|---|
| HIRES | Represents highest-resolution or highest-quality video media available for the file type. |
| LOWRES | Represents low-resolution video media for file types such as, Red (.r3d) files that support multiple qualities in the same file. |
| AUDIOSTREAM | Represents an audio clip. |
| CLIP | For particular media types, a CLIP node can act as a container of other CLIP nodes:
|
Wiretap supports the same formats as the ones supported by the Flame Family.
The IFFFS Wiretap Server allows the media files to be read in their native format with no conversion by directly accessing the file paths, or as raw RGB by reading through the server.
The WireTapClipFormat class is used to define the format of a video clip node. The WireTapAudioClipFormat class is used to define the format of an audio clip node. When instantiating a new clip node, a clip format object must be supplied as an input parameter. WireTapClipFormat also supplies a large number of constants for specifying industry-standard formats.
For more information on cached clip formats, see:
Each frame in a clip node has a frame ID. Frame IDs are unique for a particular instance of a particular Wiretap server. These classes/methods give access to the IDs of the frames on a Wiretap server:
WireTapFrameId.id() – Returns a string containing the persistent ID of a frame.
WireTapNodeHandle.getFrameId() – Returns the ID of a frame associated with a clip node. The frame is specified by its index in the set of frames associated with the clip node.
The following limitations apply to clip nodes:
Like the Creative Finishing applications, Wiretap does not permit overwriting the frames of a clip. Your Wiretap client must create a new clip and write the required frames to it.
When creating or destroying a clip node, or setting its metadata, the library (to which the clip belongs) must not be in use or opened for reading and writing by a Creative Finishing application.
Multi-channel audio in a single track/stream is not supported on write. To write multi-channel audio, use a separate AUDIOSTREAM child node for each channel.
EDL metadata is not supported for audio clips.
| C++ | Python | Description |
|---|---|---|
| listFrames.C | listFrames.py | Example of fetching frame IDs from a clip node. |
| Tool | Description |
|---|---|
wiretap_get_frames |
Fetch frame IDs from a clip node. |
wiretap_get_num_frames |
Fetch the number of frames available in a clip node. |
wiretap_set_num_frames |
Change the length of a clip node. |
wiretap_is_clip |
Validate if a given node is a clip node or not. |
wiretap_rw_frame |
Read or write a frame buffer. |
Frames can be written or linked to a clip in three ways:
By writing the frames to the clip – Only cached frames can be written to a clip node. This involves the method writeFrame of WireTapNodeHandle. See Copying Clips.
By providing source metadata – This applies to frames that are not cached, and involves getting a source data definition from the Gateway and using it to create a source clip in the IFFFS Wiretap Server. See Soft-importing Clips.
By accessing frames directly on the storage device using file paths – This can be done for frames in any standard format. This technique does not actually involve the Wiretap server when writing frames. However, the Wiretap server does supply the paths to the frames. The sample program listFrames.C shows how to obtain frame paths. This technique can improve performance when reading and writing frames. See the FAQ How do I read standard-formatted frames from a network-mounted standard FS?.
The method WireTapNodeHandle.createClipNode is used to create video and audio clip nodes.
| C++ | Python | Description |
|---|---|---|
| createClip.C | createClip.py | Example of defining a video clip format, creating a new clip node, and writing frames to it. |
| createAudio.C | createAudio.py | Example of defining an audio clip format, creating a new clip node, and writing audio samples to it. |
| Tool | Description |
|---|---|
wiretap_create_clip |
Create a video clip node. |
wiretap_create_audio |
Create an audio clip node. |
An instance of the WireTapClipFormat class can have metadata associated with it. The clip format metadata is used to describe the media in the clip. Its content is similar to the content of an image file header.
The IFFFS Wiretap Server expects clip node metadata to be in XML format. For detailed information on the format and content of the metadata, see Clip Format Metadata (XML).
Clip format metadata and its metadata tag can be set when constructing an instance of WireTapClipFormat or WireTapAudioClipFormat. The metadata tag must be XML.
The metadata can also be set and retrieved using the setMetaData and getMetaData methods on an instance of WireTapClipFormat or WireTapAudioClipFormat.
Setting metadata and the metadata tag is done as follows:
C++
WireTapStr metadata;
clipFormat.setMetaDataTag("XML");
clipFormat.setMetaData(metadata);Python
metadata = WireTapStr();
clipFormat.setMetaDataTag("XML")
clipFormat.setMetaData(metadata)where,
XML is a tag that specifies the format of the metadata stream.
metadata is a WireTapStr object that contains the XML stream. See Clip Format Metadata (XML).
Getting metadata is done as follows:
C++
clipFormat.metaData(); // this returns a string that contains the XML stream
clipFormat.metaDataTag(); // this returns "XML"Python
clipFormat.metaData() # this returns a string that contains the XML stream
clipFormat.metaDataTag() # this returns "XML"An instance of the WireTapNodeHandle class whose type is CLIP can have one or more metadata streams associated with it.
The metadata can be set and retrieved by calling the setMetaData and getMetaData methods on the WireTapNodeHandle object representing the clip node.
An Edit Decision List (EDL) is an example of metadata that can be set on a clip node. An EDL describes how the media in a clip are assembled. See Creating a Clip from an EDL Timeline.
| Tool | Description |
|---|---|
wiretap_get_metadata |
Retrieve a metadata stream from a node. |
wiretap_set_metadata |
Set a metadata stream on a node. |
wiretap_get_clip_format |
Retrieve the storage format of a clip node. |
The IFFFS Wiretap Server allows media files in standard formats (for example, DPX, QuickTime, and so on) to be imported. Importing means referencing rather than copying media to the IFFFS Wiretap Server. Once created, the imported clip will be treated like any other clip, as though it were imported by a user from a Creative Finishing workstation.
Importing frames involves fetching a source data definition from a Wiretap Gateway server and forwarding it in a createClip call to the IFFFS Wiretap Server, as shown in the above program samples.
| C++ | Python | Description |
|---|---|---|
| importOpenClips.C | importOpenClips.py | Example of creating a CLIP node and using an Open Clip located within a directory as the XML data source. |
| Tool | Description |
|---|---|
wiretap_get_metadata |
Retrieve a metadata stream from a node. |
wiretap_create_node |
Create a new node based on metadata. |
A timeline consists of video elements, audio elements, and transitions placed together chronologically on one or more parallel tracks. An Edit Decision List (EDL) is the standard format used for timelines. A Wiretap client can construct a new clip from frames in several existing clips based on an EDL that specifies frame IDs in those clips.
Wiretap treats an EDL as metadata associated with a clip node. EDL metadata can be get and set on an instance of WireTapNodeHandle whose type is CLIP by calling the getMetadata and setMetaData methods. When setting or getting EDL metadata, DMXEDL must be specified as the metadata format tag.
For detailed information on EDL format, see Clip Node Metadata (EDL).
| C++ | Python | Description |
|---|---|---|
| createTimeline.C | createTimeline.py | Example of creating a sequence from an EDL. |
When you are creating a new clip based on a timeline, the call to setMetaData actually carries out the assembly of the frames in the new clip. The frames are soft-imported or linked to the new clip. The sample createTimeline.C shows how to prepare and set EDL metadata.
When getting EDL metadata, an optional filter parameter can be used. The filter parameter is used to specify the resolution of the frames. It can be set to the following values:
high to fetch metadata about the high-resolution frames in the clip
low to fetch metadata about the low-resolution frames in the clip
all to fetch metadata about both high-resolution and low-resolution frames in the clip
Assembling clips from timelines is limited in the following ways:
An EDL cannot be applied to a clip that already contains frames.
All source nodes and the resulting new node based on the timeline must be located in the same reel (the parent reel).
The tape names in the metadata of the source clip nodes must match the tape names in the EDL.
Only cut and dissolve timeline effects are supported.
There are two methods that you can use to copy a clip.
The first method involves reading the frames of an existing clip and writing them to a new clip. The sample program readFrames.C shows how to read frames, but it does not show writing frames to a new clip.
Here are the steps that would be involved in implementing the full workflow of copying a clip:
Identify the clip node to be copied (the source clip node).
Identify the parent node of the new clip node to be created (the destination clip node).
Copy the clip format of the source clip node.
Create the destination clip node under the parent node using the copied clip format.
Copy the frames from the source clip node to a buffer by calling readFrame on the source clip node.
Copy the frames from the buffer to the destination clip node (by calling writeFrame on the destination clip node).
The second method consists of duplicating the node itself, and is shown in the sample programs duplicateNode.C and duplicateNode.py.
Here are the steps that would be involved in implementing the full workflow of duplicating a clip:
Identify the clip node to be copied (the source clip node).
Identify the parent node of the new clip node to be created (the destination clip node).
Use the duplicateNode method to create the duplicated copy under the parent node.
See also:
| C++ | Python | Description |
|---|---|---|
| readFrames.C | readFrames.py | Example of reading video frames from the server. |
| duplicateNode.C | duplicateNode.py | Example of creating a node based on another node's attributes. |
| Tool | Description |
|---|---|
wiretap_rw_frame |
Read or write a given frame in a clip node. |
wiretap_client_tool |
Multi-purpose tool that can be used to copy a clip node to another. |