Shape analysis¶
Shapes can be analyzed to detect for example detect cropping and silence.
New in version 4.4.
Analysis will also generation information for generating waveform data, to be visualized in a UI.
Operations¶
Analyze a shape¶
-
POST
/item/
(item-id)/shape/
(shape-id)/analyze
¶ Analyzes the specified shape with the parameters specified in the job document. The result of the analyze will appear in the RestBulkyMetadata of the shape.
Query Parameters: - notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
Accepts: - application/xml, application/json – AnalyzeJobDocument
Produces: - application/xml, application/json – JobDocument
Role: _job_write
Example¶
Analyze a shape with default parameters:
POST /item/VX-123/shape/VX-456/analyze
Content-Type: application/xml
<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine"/>
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<jobId>VX-426</jobId>
<user>admin</user>
<started>2012-03-26T11:27:49.173Z</started>
<status>READY</status>
<type>ANALYZE</type>
<priority>MEDIUM</priority>
</JobDocument>
Example¶
Analyze a shape with custom parameters:
POST /item/VX-124/shape/VX-457/analyze
Content-Type: application/xml
<AnalyzeJobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<black>
<threshold>0.1</threshold>
<percentage>95</percentage>
</black>
<freeze>
<time>1.0</time>
<threshold>0.05</threshold>
</freeze>
<bars>
<percentage>10</percentage>
<threshold>0.05</threshold>
</bars>
</AnalyzeJobDocument>
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<jobId>VX-427</jobId>
<user>admin</user>
<started>2012-03-26T11:27:49.173Z</started>
<status>READY</status>
<type>ANALYZE</type>
<priority>MEDIUM</priority>
</JobDocument>
In this example, settings for black frame, freeze and bar detection are
included. The threshold
elements determine the threshold to use when
detecting black frames or freezes. The values have the following meaning:
threshold
for black frame detection and bar detection denotes that any pixel whose value is greater thanthreshold
* 255 should not be regarded as black. I.e. only ifthreshold
is 0 will only completely black pixels be counted.- For freeze frame detection
threshold
determines how much any one pixel may change between two frames. If the difference in value between two frames is greater thanthreshold
* 255, the frame will not be regarded as frozen.
Viewing the results¶
The results of the analysis is stored in the bulky metadata for the shape. For
example, to view the black frame information (if available), go to
/item/VX-123/shape/VX-456/metadata/bulky/black
. You should see something
like the following:
<BulkyMetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-295">
<field stream="0" end="6@50" start="0@50">
<key>black</key>
<value>1</value>
</field>
<field stream="0" end="1650@50" start="1490@50">
<key>black</key>
<value>1</value>
</field>
</BulkyMetadataDocument>
Each field contains a start
and an end
attribute, denoting the start
and end timecodes for the black frames.
Loudness analysis¶
When an analysis is done, a loudness analysis is done automatically. The result of the loudness analysis is written to the bulky metadata, but there are utility methods to easily extract the information.
Get loudness values¶
-
GET
/item/
(item-id)/loudness
¶ Extracts loudness information from bulky metadata.
Produces: - application/xml, application/json – LoudnessDocument
Role: _item_shape_read
Example¶
POST /item/VX-124/shape/VX-457/analyze
GET /item/VX-124/loudness
<LoudnessDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<id>VX-124</id>
<shape>VX-457</shape>
<shapeTag>original</shapeTag>
<mix>
<name>Left</name>
<weightdB>0.0</weightdB>
<sourceStream>0</sourceStream>
<sourceChannel>0</sourceChannel>
</mix>
<mix>
<name>Right</name>
<weightdB>0.0</weightdB>
<sourceStream>0</sourceStream>
<sourceChannel>1</sourceChannel>
</mix>
<mix>
<name>Center</name>
<weightdB>0.0</weightdB>
</mix>
<mix>
<name>Left Surround</name>
<weightdB>1.5</weightdB>
</mix>
<mix>
<name>Right Surround</name>
<weightdB>1.5</weightdB>
</mix>
<startLoudness>0@48000</startLoudness>
<endLoudness>1339200@48000</endLoudness>
<startRange>0@48000</startRange>
<endRange>1296000@48000</endRange>
<loudnessLU>0.014140396527686505</loudnessLU>
<loudnessRangeLU>4.974758665644899</loudnessRangeLU>
</LoudnessDocument>
Get loudness values for interval¶
-
PUT
/item/
(item-id)/loudness
¶ Extracts loudness information from bulky metadata. Start and end range can be specified, as well as custom mixing.
Accepts: - application/xml, application/json – LoudnessDocument
Produces: - application/xml, application/json – LoudnessDocument
Role: _item_shape_read
Waveform information¶
New in version 4.4.
The waveform data is not exactly the waveform, but measurements of the RMS values with a rather high sampling rate.
Get waveform data¶
New in version 4.5.1.
-
GET
/item/
(item-id)/waveform/values
¶ Query Parameters: - itemTrack – The itemTrack value of the audio channel within the shape. (Optional)
- stream – The stream value of the audio channel within the component of the shape. (Optional)
- channel – The channel value of the audio channel within the stream of the component. Optional, if omitted the first channel. If itemTrack and stream are omitted, this value can be used to denote tracks in a linear fashion, regardless of itemTrack and stream. Then channel=0 means the first audio track, channel=1 the second, etc.
- shape – The shape id to use to get information from. Optional, if omitted the shape tag will be used. Note that an analysis of this shape must be done before the information is available.
- tag – The shape tag to use. Optional, if omitted the
original
shape tag will be used. - start – The start time code to get waveform information for. Default is
-INF
. - end – The end time code to get waveform information for. Default is
+INF
. - dB –
true
- Return RMS dB values.
false
(default)- Return RMS 1-based absolute values.
- width – The number of sample points to return. Default is 400.
Produces: - application/xml, application/json – WaveformDataDocument
Role: _item_shape_read
Get waveform data (deprecated)¶
Deprecated since version 4.5.1.
-
GET
/item/
(item-id)/waveform/data
¶ Query Parameters: - itemTrack – The itemTrack value of the audio channel within the shape. (Optional)
- stream – The stream value of the audio channel within the component of the shape. (Optional)
- channel – The channel value of the audio channel within the stream of the component. Optional, if omitted the first channel. If itemTrack and stream are omitted, this value can be used to denote tracks in a linear fashion, regardless of itemTrack and stream. Then channel=0 means the first audio track, channel=1 the second, etc.
- shape – The shape id to use to get information from. Optional, if omitted the shape tag will be used. Note that an analysis of this shape must be done before the information is available.
- tag – The shape tag to use. Optional, if omitted the
original
shape tag will be used. - start – The start time code to get waveform information for. Default is
-INF
. - end – The end time code to get waveform information for. Default is
+INF
. - dB –
true
- Return RMS dB values.
false
(default)- Return RMS 1-based absolute values.
- width – The number of sample points to return. Default is 400.
Produces: - application/json – A JSON array with one JSON object. The JSON object contains
one value with key
data
. The value is a JSON array withwidth
number of data points.
Role: _item_shape_read
Get waveform image¶
-
GET
/item/
(item-id)/waveform/image
¶ Query Parameters: - itemTrack – The itemTrack value of the audio channel within the shape. (Optional)
- stream – The stream value of the audio channel within the component of the shape. (Optional)
- channel – The channel value of the audio channel within the stream of the component. Optional, if omitted the first channel. If itemTrack and stream are omitted, this value can be used to denote tracks in a linear fashion, regardless of itemTrack and stream. Then channel=0 means the first audio track, channel=1 the second, etc.
- shape – The shape id to use to get information from. Optional, if omitted the shape tag will be used. Note that an analysis of this shape must be done before the information is available.
- tag – The shape tag to use. Optional, if omitted the
original
shape tag will be used. - start – The start time code to get waveform information for. Default is
-INF
. - end – The end time code to get waveform information for. Default is
+INF
. - dB –
true
- Return RMS dB values.
false
(default)- Return RMS 1-based absolute values.
- width – The number of sample points to return. Default is 400.
- height – The height, in pixels, of the image. Default is 100.
- bgcolor – The background color of the image, as hex triplet. Defaults to
#000000
(black). - fgcolor – The color of the waveform, as hex triplet. Defaults to white.
- hgridline – The position of primary horizontal gridlines, in units of the audio. Default is no gridline.
- hgridlinecolor – The color of primary horizontal gridlines.
- hgridline2 – The position of secondary horizontal gridlines, in units of the audio. Default is no gridline.
- hgridline2color – The color of secondary horizontal gridlines.
- vgridline – The position of primary vertical gridlines, where 0 is left border and 1 is right border. Default is no gridline.
- vgridlinecolor – The color of primary vertical gridlines.
- vgridline2 – The position of primary vertical gridlines, where 0 is left border and 1 is right border. Default is no gridline.
- vgridline2color – The color of primary vertical gridlines.
- min – The audio value that corresponds the bottom border. Defaults to -1 if
dB
is false, and -80 otherwise. - max – The audio value that corresponds the top border. Defaults to 1 if
dB
is false, and 0 otherwise.
Produces: - image/png – A PNG image with the waveform drawn on the canvas described by the query parameters.
Role: _item_shape_read
Get waveform image URI¶
New in version 4.5.1.
-
GET
/item/
(item-id)/waveform/imageURI
¶ Query Parameters: - itemTrack – The itemTrack value of the audio channel within the shape. (Optional)
- stream – The stream value of the audio channel within the component of the shape. (Optional)
- channel – The channel value of the audio channel within the stream of the component. Optional, if omitted the first channel. If itemTrack and stream are omitted, this value can be used to denote tracks in a linear fashion, regardless of itemTrack and stream. Then channel=0 means the first audio track, channel=1 the second, etc.
- shape – The shape id to use to get information from. Optional, if omitted the shape tag will be used. Note that an analysis of this shape must be done before the information is available.
- tag – The shape tag to use. Optional, if omitted the
original
shape tag will be used. - start – The start time code to get waveform information for. Default is
-INF
. - end – The end time code to get waveform information for. Default is
+INF
. - dB –
true
- Return RMS dB values.
false
(default)- Return RMS 1-based absolute values.
- width – The number of sample points to return. Default is 400.
- height – The height, in pixels, of the image. Default is 100.
- bgcolor – The background color of the image, as hex triplet. Defaults to
#000000
(black). - fgcolor – The color of the waveform, as hex triplet. Defaults to white.
- hgridline – The position of primary horizontal gridlines, in units of the audio. Default is no gridline.
- hgridlinecolor – The color of primary horizontal gridlines.
- hgridline2 – The position of secondary horizontal gridlines, in units of the audio. Default is no gridline.
- hgridline2color – The color of secondary horizontal gridlines.
- vgridline – The position of primary vertical gridlines, where 0 is left border and 1 is right border. Default is no gridline.
- vgridlinecolor – The color of primary vertical gridlines.
- vgridline2 – The position of primary vertical gridlines, where 0 is left border and 1 is right border. Default is no gridline.
- vgridline2color – The color of primary vertical gridlines.
- min – The audio value that corresponds the bottom border. Defaults to -1 if
dB
is false, and -80 otherwise. - max – The audio value that corresponds the top border. Defaults to 1 if
dB
is false, and 0 otherwise.
Produces: - text/plain – A URI that does not require authentication to the generated image. The URI expires after 1 hour.
Role: _item_shape_read
Get waveform images for all audio channels¶
Solely used for debugging. May be deprecated in newer releases.
-
GET
/item/
(item-id)/waveform/alltracks
¶ Query Parameters: - itemTrack – The itemTrack value of the audio channel within the shape. (Optional)
- stream – The stream value of the audio channel within the component of the shape. (Optional)
- channel – The channel value of the audio channel within the stream of the component. Optional, if omitted the first channel. If itemTrack and stream are omitted, this value can be used to denote tracks in a linear fashion, regardless of itemTrack and stream. Then channel=0 means the first audio track, channel=1 the second, etc.
- shape – The shape id to use to get information from. Optional, if omitted the shape tag will be used. Note that an analysis of this shape must be done before the information is available.
- tag – The shape tag to use. Optional, if omitted the
original
shape tag will be used. - start – The start time code to get waveform information for. Default is
-INF
. - end – The end time code to get waveform information for. Default is
+INF
. - dB –
true
- Return RMS dB values.
false
(default)- Return RMS 1-based absolute values.
- width – The number of sample points to return. Default is 400.
- height – The height, in pixels, of the image. Default is 100.
- bgcolor – The background color of the image, as hex triplet. Defaults to
#000000
(black). - fgcolor – The color of the waveform, as hex triplet. Defaults to white.
- hgridline – The position of primary horizontal gridlines, in units of the audio. Default is no gridline.
- hgridlinecolor – The color of primary horizontal gridlines.
- hgridline2 – The position of secondary horizontal gridlines, in units of the audio. Default is no gridline.
- hgridline2color – The color of secondary horizontal gridlines.
- vgridline – The position of primary vertical gridlines, where 0 is left border and 1 is right border. Default is no gridline.
- vgridlinecolor – The color of primary vertical gridlines.
- vgridline2 – The position of primary vertical gridlines, where 0 is left border and 1 is right border. Default is no gridline.
- vgridline2color – The color of primary vertical gridlines.
- min – The audio value that corresponds the bottom border. Defaults to -1 if
dB
is false, and -80 otherwise. - max – The audio value that corresponds the top border. Defaults to 1 if
dB
is false, and 0 otherwise.
Produces: - text/html – An HTML document including image references to waveform images for all channels. Query parameters can be used to control the image appearance.
Role: _item_shape_read