8.0

Rendered v8.0 specification

What's Changed

• Improvements to webhooks endpoints by @j616 in #142
  • Adds additional endpoints for improved management of webhooks. Adds additional status/error reporting to webhooks metadata.
• ADR0040: Discuss making framerate mandatory for video, allowing VFR flag by @samdbmg in #143
  • Variable frame rate video is now signalled explicitely via the vfr parameter. If vfr is false or unset, frame_rate MUST be set.
• Make label mandatory when registering uncontrolled Object Instances by @j616 in #155
  • label is now mandatory when registering uncontrolled Object Instances (i.e. get_urls that aren't controlled by the TAMS Service Instance)
• Improve usability of tags by @samdbmg in #153
  • Adds support for arrays as a tag value type. Adds tags to webhooks.
• adr0036: Handle partial segment usage better by @samdbmg in #147
  • Adds a timerange to Objects and deprecated sample_count and sample_offset. Improves documentation on partial-object use
• Add Object Instance management endpoints by @j616 in #144
  • Adds Object Instance management endpoints. Expands Object Instance metadata and filtering options. Promotes AppNote 0009 formatted Instance label metadata to core spec.
• Proposal to remove pre-actions from storage endpoint by @j616 in #148
  • Removed pre-actions and put_cors_url from /flows/<id>/storage response. These properties pre-date the open-sourcing of TAMS and we are unaware of any real world use or use cases.
• Allow ts_offset to be a negative offset by @samdbmg in #140
  • Only changes the description which was erroneously strict
• Clarify behaviour on conflicting Flow/Source metadata by @j616 in #146
  • Clarifies that store implementations should verify that Flow metadata is compatible with the associated Source
• Better explain how to work out which parts of a media object to use by @samdbmg in #141
  • Adds further explanatory documentation on how to work out which part of an object a segment uses
• Audit and update TAMS documentation and specification by @j616 in #149
  • Generally improved the consistency and clarity of documentation.
• examples: Add option to supply Flow metadata by @samdbmg in #145
  • Allows custom Flow metadata to be provided to HLS ingest example
• examples: Tweak the outgest script for presigned by @samdbmg in #151
  • Outgest example script modified such that it requests pre-signed URLs
• appnote: Fix error in deleting object instances by @samdbmg in #152
  • Fixes an error in the above Object Instance management PR

Implementation considerations

This section calls out changes implementations may need/want to make. It also calls out behaviour which has been clarified where developers should verify their implementations.

Service Considerations

• New Object Instance management endpoints
  • Add new Object Instance management endpoints/functionality
    • Note: Ensure that clients cannot delete the last Instance of an Object via these endpoints
  • Add/migrate metadata from Flows to Objects as required
  • Populate managed Object Instance metadata from Storage Backend metadata as required
  • Add new Object filtering options to Objects and Segments endpoints
  • With the deprecation of AppNote 0009 formatted labels, consider using labels for more descriptive Storage Backend naming
• Mandatory labels on uncontrolled Object Instances
  • Services should reject requests that register uncontrolled Object Instances that don’t have label set
  • Verify that there are no duplicate labels in requests to register instances
  • Services should choose a sensible default label for existing uncontrolled Object Instances which don’t have one
• Webhooks improvements
  • Add the new webhooks management endpoints
  • Ensure that it is possible to register multiple webhooks with different configurations that target the same endpoint
  • Ensure that removing all events from a webhook configuration does not result in the deletion of the webhooks
• Tag improvements
  • Add support for lists as a supported type for tag values
  • Add tags to webhooks
  • Adds support for list tag values to tag filters
• Mandatory frame rate, and new variable frame rate flag
  • Add separate vfr parameter to video Flows
  • Validate the combinations of vfr value and frame_rate presence
• Changes to better support partial segment re-use
  • Add timerange property to Objects
    • Note that this parameter is called object_timerange when referred to in contexts other than the Objects endpoints
    • Implementations should consider the best way to populate this field for existing content
      • If implementations can be certain Flow Segments only use full Objects, this may be set to the timerange offset by ts_offset of the segment(s) using the Object
      • If implementations can be certain at least one Flow Segment uses the full Object, this may be set to the timerange offset by ts_offset of the segment using the Object with the largest timerange duration
      • If implementations cannot be certain of the above, they may have to inspect the timing of the Object using a tool such as ffprobe
      • Note that sample_count and sample_offset should not be relied upon as they capture the unused samples in the Object before the Segment(s), but not unused samples after the Segment(s). They also do not take into account the effect of missing samples on the time range.
  • Add the query parameters that enable the inclusion of Object timerange on the Objects and Segments endpoints
  • Add logic to set the Object timerange to the Segment timerange offset by ts_offset when not explicitly provided by the client
  • Reject the registration of Segments who’s timerange offset by ts_offset fall outside of the relevant Object’s timerange
• Correction to ts_offset description
  • Verify negative ts_offset is supported
• Clarification on conflicting Source/Flow metadata
  • Verify that Flow creation/modification requests are rejected when incompatible with their Source’s metadata
• Removal of pre-actions and put_cors_url from Storage endpoint
  • Services should no longer return pre-actions or put_cors_url with put_urls

Client Considerations

• Changes to better support partial segment re-use
  • Writing clients should set the object_timerange property on the Segment where and Object is first registered if the complete Object isn’t used
  • Consuming clients should move to using object_timerange, Segment timerange, and Segment ts_offset for operations in place of the now deprecated sample_count and sample_offset parameters
• Tag improvements
  • Add support for list tag value types as required, particularly where tags are presented to users
• Webhooks improvements
  • Where clients support the management of existing webhooks, update to use the new management mechanisms
  • Creation of webhooks is backwards compatible
• New Object Instance management endpoints
  • Clients should ensure that key_frame_count is set to the number of key frames in the Object, not the Segment
  • Add support for Object Instance management as required
  • Add support for new Object Instance filter options as required
  • Add support for new Object Instance parameters on the the Objects and Flow Segments endpoints as required, particularly when registering unmanaged Instances
• Mandatory frame rate, and new variable frame rate flag
  • Writing clients which support variable frame rates should set the vfr flag as required
  • Writing clients MUST always set frame_rate when vfr is False or unset
  • Reading clients should still be able to identify VFR content based on the presence of frame_rate, but should prefer using the value of vfr for this purpose
• Clarification on conflicting Source/Flow metadata
  • Verify that Flow creation/modifications are compatible with related Source
• Removal of pre-actions and put_cors_url from Storage endpoint
  • Clients no longer need to handle pre-actions or put_cors_url
• Mandatory labels on uncontrolled Object Instances
  • Clients registering uncontrolled Object Instances MUST set label on the Instances
  • Client implementors should verify that their code won’t attempt to register duplicate labels

Full Changelog: 7.0...8.0