Shape components¶
Components¶
List all components for a shape¶
-
GET
/item/
(id)/shape/
(shape-id)/component
¶ Returns all components for a specified shape. Currently, this call returns the same information as the return shape, but is available for orthogonality.
Status Codes: - 404 Not found – Invalid id
Produces: - application/xml, application/json – ComponentListDocument
Role: _item_shape_read
Retrieve a component¶
-
GET
/item/
(id)/shape/
(shape-id)/component/
(component-id)¶ Returns all files, or the complete component information, for a specified component.
Query Parameters: - full (boolean) –
true
- Return the component information.false
(default) - Return all files.
Produces: - application/xml, application/json – ComponentDocument if
full=true
, else a FileListDocument. - text/plain – List of file URLs
Role: _item_shape_read
- full (boolean) –
Component import¶
Import a component using a URI or an existing file¶
-
POST
/item/
(id)/shape/
(shape-id)/component
¶ Starts a job that imports a component to an existing shape. The shape must be a media shape and must not be a placeholder.
Query Parameters: - uri (string) – The URI to the file containing the new shape.
- fileId (string) – The id of the file that contains the new shape.
- allowReimport (boolean) –
true
- Import the file to this shape even if the file is already importing or is already part of another item.false
(default) Reject the request if the file with the given id has already been imported or is currently importing.
- notification (string) – The placeholder job notification to use for this job.
- notificationData (string) – Any additional data to include for notifications on this job.
- priority (string) – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata (string[]) – Additional information for the job task.
- holdJob (boolean) – If set to
true
, the job will be created in aHOLD
state. Default isfalse
.
Produces: - application/xml, application/json – JobDocument
Status Codes: - 400 – If the file has already been imported.
Role: _import
Component analysis¶
Analyze a component¶
-
POST
/item/
(item-id)/shape/
(shape-id)/component/
(component-id)/analyze
¶ Analyzes a shape component with the parameters specified in the job document. Only VidiCoder is currently supported.
New in version 21.4.
Query Parameters: - resourceId (string) – The transcoder or cognitive service resource to use to execute the analysis.
- storageId (string) – The storage on which to store a temporary analysis data file when using a Vidinet transcoder to analyze a component. If no storage id has been specified Vidispine will (by default) automatically pick a supported storage. The storage id will be ignored when using a non Vidinet transcoder.
- callbackId (string) – The callback resource id to use for finding and running callback scripts.
- notification (string) – The placeholder job notification to use for this job.
- notificationData (string) – Any additional data to include for notifications on this job.
- priority (string) – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata (string[]) – Additional information for the job task.
- holdJob (boolean) – If set to
true
, the job will be created in aHOLD
state. Default isfalse
.
Accepts: - application/xml, application/json – AnalyzeJobDocument
Produces: - application/xml, application/json – JobDocument
Role: _job_write
Analyze a shape component using an analyze preset¶
-
POST
/item/
(item-id)/shape/
(shape-id)/component/
(component-id)/analyze
¶ Analyzes the shape component with the parameters from the analyze preset specified. Only VidiCoder and Baton QC is currently supported.
New in version 21.4.
Query Parameters: - preset (string) – The analyze preset to use for the job
- resourceId (string) – The transcoder or cognitive service resource to use to execute the analysis.
- storageId (string) – The storage on which to store a temporary analysis data file when using a Vidinet transcoder to analyze a component. If no storage id has been specified Vidispine will (by default) automatically pick a supported storage. The storage id will be ignored when using a non Vidinet transcoder.
- callbackId (string) – The callback resource id to use for finding and running callback scripts.
- notification (string) – The placeholder job notification to use for this job.
- notificationData (string) – Any additional data to include for notifications on this job.
- priority (string) – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata (string[]) – Additional information for the job task.
- holdJob (boolean) – If set to
true
, the job will be created in aHOLD
state. Default isfalse
.
Produces: - application/xml, application/json – JobDocument
Role: _job_write
Move/copy components¶
Move a component to another shape¶
-
POST
/item/
(id)/shape/
(shape-id)/component/
(component-id)/move/item/
(target-id)/shape/
(target-shape-id)¶ Move this component to another shape.
Query Parameters: - index (integer) – The component index (track) of component. If the target shape has a component with this index, then it will be replaced/removed.
- keepMetadata (boolean) –
true
- Preserve the metadata from the replaced component.false
(default) - Discard any metadata from the replaced component.
Produces: - application/xml, application/json – ShapeDocument from the target shape.
Role: _item_shape_write
Move a component to another shape/component¶
-
POST
/item/
(id)/shape/
(shape-id)/component/
(component-id)/move/item/
(target-id)/shape/
(target-shape-id)/component/
(target-component-id)¶ Move this component to another shape, replacing a specific component by id.
Query Parameters: - index (integer) – The component index (track) of component. If the target shape has a component with this index, then it will be replaced/removed.
- keepMetadata (boolean) –
true
- Preserve the metadata from the replaced component.false
(default) - Discard any metadata from the replaced component.
Produces: - application/xml, application/json – ShapeDocument from the target shape.
Role: _item_shape_write
Copy a component to another shape¶
-
POST
/item/
(id)/shape/
(shape-id)/component/
(component-id)/copy/item/
(target-id)/shape/
(target-shape-id)¶ Copy this component to another shape.
Query Parameters: - index (integer) – The component index (track) of component. If the target shape has a component with this index, then it will be replaced/removed.
- keepMetadata (boolean) –
true
- Preserve the metadata from the replaced component.false
(default) - Discard any metadata from the replaced component.
Produces: - application/xml, application/json – ShapeDocument from the target shape.
Role: _item_shape_write
Copy a component to another shape/component¶
-
POST
/item/
(id)/shape/
(shape-id)/component/
(component-id)/copy/item/
(target-id)/shape/
(target-shape-id)/component/
(target-component-id)¶ Copy this component to another shape, replacing a specific component by id.
Query Parameters: - index (integer) – The component index (track) of component. If the target shape has a component with this index, then it will be replaced/removed.
- keepMetadata (boolean) –
true
- Preserve the metadata from the replaced component.false
(default) - Discard any metadata from the replaced component.
Produces: - application/xml, application/json – ShapeDocument from the target shape.
Role: _item_shape_write
Delete a component¶
-
DELETE
/item/
(id)/shape/
(shape-id)/component/
(component-id)¶ Removes the component from the shape. Any files belonging to the component is not Copy this component to another shape, replacing a specific component by id.
Query Parameters: - keepFiles (boolean) –
true
- Keep the files belong to this shape.false
(default) - Remove the files belong to this shape.
Role: _item_shape_write
- keepFiles (boolean) –
Component files¶
Associate a file with a component¶
-
PUT
/item/
(id)/shape/
(shape-id)/component/
(component-id)/file/
(file-id)¶ Attaches the specified file to the specified component
Query Parameters: - allowReimport (boolean) –
true
- Associate the file regardless of whether it already belongs to a component.false
(default) - Only files that do not already belong to a component can be associated.
Produces: - application/xml, application/json – ComponentDocument
Role: _item_shape_write
- allowReimport (boolean) –
Remove a file from a component¶
-
DELETE
/item/
(id)/shape/
(shape-id)/component/
(component-id)/file/
(file-id)¶ Removes the specified file from the specified component
Role: _item_shape_write
Placeholder components¶
Create a placeholder component¶
-
POST
/item/
(id)/shape/
(shape-id)/component/placeholder
¶ Creates an new placeholder component for a specific shape.
Query Parameters: - type (string) – The type of component. Required. One of
audio
,video
,container
orbinary
. - index (integer) – The component index (track) of new component.
Produces: - application/xml, application/json – ComponentDocument
- type (string) – The type of component. Required. One of
Component metadata¶
Please refer to Key-value metadata.