Redaction with an Embedded Editor
Note
Redactor v5 introduces many improvements to the API and embedded UI. The article below applies to early Redactor v4 integrations. If you are on v5, please see the new Embedded Redactor with Multi-Video Projects example. Contact support@sighthound.com with any questions.
Create a New Redactor Session
Start a new Redactor session by providing a path to the video to be redacted in inputUri and a path to a storage bucket in outputUri. It's important to note that a trailing slash is required in the outputURI if the destination is a folder and not a specific file. You can optionally specify a webhook for progress, start, and/or completion events. The API service will respond with a name, which we refer to as the "operation name", that will be used to query progress and receive details needed for future redaction calls for this specific session.
POST /api/v1/videos:process
REQUEST
{
"features": ["MEDIA_PREPARE"],
"inputUri": "https://example.com/path/to/video.mp4",
"notifications": [{
"method": "HTTP_POST",
"uri": "https://example.com/mywebhook/endpoint",
"events": ["START", "PROGRESS", "COMPLETION"]
}],
"outputUri": "https://{your_azure_account}.blob.core.windows.net/{container_name}/{optional_folder}/"
}
RESPONSE
Project initialization is not instantaneous. The example above uses webhooks and will receive POST messages to the specified endpoint for START, PROGRESS, and COMPLETION events. Alternatively, the operation status can be monitored by polling the /api/v1/{operation-name} endpoint using the full name returned in the response above. This name value is also provided in the webhook notification document for convenience.
Get Operation Status
All requests sent to the /api/v1/videos:process endpoint are asynchronous, with each returning an operation name like:
This name is used to both identify a specific Redactor project, and to inspect the status of the operation. When the done value is true, the operation is complete and the response value will contain additional information.
GET /api/v1/{operation-name}
REQUEST
GET /api/v1/projects/{project_id}/locations/{location_id}/operations/{operation_id}
RESPONSE
{
"name": "projects/{project_id}/locations/{location_id}/operations/{operation_id}",
"metadata": {
"@type": "sighthound.cloud.v1.Progress",
"progress": {
"inputUri": "http://example.com/path/to/video.mp4",
"progressPercent": 100,
"startTime": "2020-04-01T22:13:17.978847Z",
"updateTime": "2020-04-01T22:13:29.576004Z"
}
},
"done": true,
"response": {
"@type": "sighthound.cloud.v1.videos.ProcessResponse",
"processResults": {
"outputUri": "https://{your_azure_account}.blob.core.windows.net/{container_name}/{optional_folder}/"
}
}
}
Important: The response.processResults.outputUri value in the operation response references the Redactor project’s storage location that needs to be used as the inputUri (instead of the actual video URL) for all future API calls for this specific project. By default, it will be the same as the outputURI specified in the original request.
Webhook Notifications
When notifications are specified in any of the Redactor API requests, the Redactor server will POST messages that contain the same content as Get Operation Status above.
Instantiate the Redactor Editor UI
Once you've received notification that the original MEDIA_PREPARE operation is complete, you can instantiate the editor UI on your website. To do so, simply include the sighthound-redactor.js script in the HEAD of your website and render the editor to your desired location.
<html>
<head>
<title>Redactor Integration Demo</title>
<script src="sighthound-redactor.js"></script>
</head>
<body>
<!-- Example button to close and clean up the Editor session. -->
<button
id="closeBtn"
onClick="onCleanup()"
style="color: darkblue; position: absolute; top: 10px; left: 10px; z-index: 100;"
>Close Video</button>
<!-- This div is where the editor will appear once rendered -->
<div id="redactor-editor"></div>
<script>
// Publicly accessible URL to the Redactor server which the editor will connect.
const redactorServer = "http://localhost:9000";
// The storage location for this user's project. It's the "outputUri" used in MEDIA_PREPARE call.
const redactorStorageUri = "https://{your_azure_account}.blob.core.windows.net/{container_name}/{optional_folder}/";
// Instantiate a new editor by providing the div id where to render and the variables above.
const redactorEditor = new redactor.default(
document.getElementById("redactor-editor"),
redactorServer,
redactorStorageUri,
);
// Render the editor to the screen. It's important to do this only after MEDIA_PREPARE is complete.
redactorEditor.renderEditor();
// It's good practice to disconnect the UI from the remote Redactor server when done.
function onCleanup() {
redactorEditor.cleanup();
document.getElementById("closeBtn").style.display = "none"; // hide button
}
</script>
</body>
</html>
At this point, the Redactor editor should display the video and allow the user to fully use the redaction tools.
Exporting the Redacted Video
The Editor UI displays an Export Video button which the user can click to render and download the redacted video directly to their computer. If you would prefer to control that process instead, you can hide the Export Video button using CSS and make another API call to the Redactor server. If an outputUri is not provided, the outputUri specified in the original MEDIA_PREPARE call will be used. All of the project's state will be synced to that location and the redacted video will be saved with the filename redacted.mp4. If you would like to save only the video to a new location, you can provide a new outputUri that ends with a filename instead of a folder.
POST /api/v1/videos:process
REQUEST
{
"inputUri": "https://{your_azure_account}.blob.core.windows.net/{container_name}/{optional_folder}/",
"features": ["MEDIA_RENDERING"],
"notifications": [{
"method": "HTTP_POST",
"uri": "https://example.com/mywebhook/endpoint",
"events": ["PROGRESS", "COMPLETION"]
}],
"outputUri": "https://{your_azure_account}.blob.core.windows.net/{container_name}/redacted.mp4",
}
RESPONSE
Optional: Automatically Detect and Track Objects
Note: The Redactor Editor UI can start an auto-redaction without needing to directly call this endpoint. This example is included in case the developer wants to start an auto-redaction before showing the UI.
POST /api/v1/videos:process
REQUEST
{
"inputUri": "https://{your_azure_account}.blob.core.windows.net/{container_name}/{optional_folder}/",
"features": ["FACE_DETECTION", "VEHICLE_DETECTION"],
"notifications": {
"method": "HTTP_POST",
"uri": "https://example.com/mywebhook/endpoint",
"events": ["PROGRESS", "COMPLETION"]
}
}