SG Ground Truth

media on a take

Put a video or audio clip on a custom entity row so a browser can play it, and know when it is ready

API

A plain Attachment keeps a clip and makes a thumbnail at most. A Version whose entity is the row makes an H.264 or aac mp4 every browser plays, from HEVC and Opus too (probes 151, 152).

Call

import time

import requests


def clip_on_row(c, project_id, row_type, row_id, path, mime, code=None):
    """One Version per clip. `mime` is what a browser's fetch sends for the File."""
    v = c.post("/entity/versions", json={
        "project": {"type": "Project", "id": project_id}, "code": code or path.name,
        "entity": {"type": row_type, "id": row_id}}).json()["data"]["id"]
    i = c.get(f"/entity/versions/{v}/sg_uploaded_movie/_upload", params={"filename": path.name}).json()
    requests.put(i["links"]["upload"], data=path.read_bytes(), headers={"Content-Type": mime}).raise_for_status()
    c.post(i["links"]["complete_upload"], json={"upload_info": i["data"], "upload_data": {}}).raise_for_status()
    return v


def wait_playable(c, version_id, timeout=300):
    """The transcode's URL once status is 1. Signed for 900 s: read it again to play later."""
    t0 = time.time()
    while time.time() - t0 < timeout:
        a = c.get(f"/entity/versions/{version_id}", params={
            "fields": "sg_uploaded_movie_transcoding_status,sg_uploaded_movie_mp4,uploaded_movie_duration,image"
        }).json()["data"]["attributes"]
        if a["sg_uploaded_movie_transcoding_status"] == 1 and a["sg_uploaded_movie_mp4"]:
            return a
        time.sleep(10)
    return None

Response

POST /entity/versions entity=<custom entity row>      -> 201, entity reads back the row
init data.upload_type "Attachment"; PUT 200; complete 201

            ready at   sg_uploaded_movie_mp4              image          duration
h264 .mp4   46 s       h264 1280x720 24/1 + aac, mp4      JPEG 480x270   "4.01"
hevc .mov   59 s       h264 1280x720 24/1 + aac, mp4      JPEG 480x270   "4.01"
aac .m4a    34 s       aac only, mp4                      null           "4.01"
opus .webm  46 s       aac only, mp4                      null           "4.0"

Notes

  • sg_uploaded_movie keeps the original byte for byte; play sg_uploaded_movie_mp4, and store ids, not URLs (probe 125).
  • Audio has no thumbnail: image goes from the transient placeholder to null. Draw the icon yourself.
  • The stored content_type is the server's: an Opus .webm reads video/webm. Tell audio from video on the client.
  • Any custom slot is accepted as Version.entity at 201, valid_types or not (probe 122, field_types/entity). A type with an sg_versions field also lists the Version there (probe 122).
  • A large clip goes up in parts (probe 044) and each part URL lives 900 s (probes 125, 153).

Every entry on this site is the output of a probe in probes/. The corpus is generated by running those probes against a live Flow Production Tracking site, not written from memory.

Not affiliated with or endorsed by Autodesk. Flow Production Tracking is their product; this is an independent record of how its REST API answers.