Shape analysis¶
Shapes can be analyzed to detect for example detect cropping and silence.
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
- settings – Pre-configured import settings. See Import settings
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 than threshold * 255 should not be regarded as black. I.e. only if threshold 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 than threshold * 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