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

7.0

What's Changed

• Restrict timestamp and timerange patterns by @philipnbbc in #114
• Only run CI job on fork PRs by @j616 in #119
• danjhd/hls-tags by @danjhd in #116
• johnbilt - Bulk flow segments by @johnbilt in #117
• Allow TAMS to support Flow / storage external media objects by @philipnbbc in #120
• Proposal for an objects endpoint by @philipnbbc in #111
• Add AppNote0017 on when to reuse IDs by @j616 in #121
• added missing query parameter for HEAD /sources by @danjhd in #123
• Add common scopes to example scripts by @j616 in #126
• ADR for flow image support by @johnbilt in #122
• Mark ADR0031 as accepted by @j616 in #127
• Mark ADR0030 accepted by @j616 in #128
• Fix: remove extra quotes from code block on app note 0014 by @himslm01 in #133
• storage endpoint - support object ids by @danjhd in #132
• Describe authentication methods in TAMS API by @samdbmg in #113
• Mark ADRs as accepted by @j616 in #135
• Add workflow to check ADR statuses, and ADR & App Note listings by @j616 in #136
• Bugfix: Remove container mapping from source collections by @j616 in #134
• Specifying storage location when requesting storage allocation by @j616 in #125
• Use deploy key in release workflow by @j616 in #137
• Add missing verbose_storage parameter to webhook post by @j616 in #138
• Rename object_id to id on the objects endpoint by @j616 in #139

New Contributors

• @danjhd made their first contribution in #116
• @johnbilt made their first contribution in #117
• @himslm01 made their first contribution in #133

Full Changelog: 6.0...7.0

6.0

What's Changed

• Add Flow and Source filter options for webhook events by @philipnbbc in #84
• appnote: Add appnote on long-running Flows/Sources by @samdbmg in #85
• Application note for working with C2PA provenance in TAMS by @chalford in #87
• Add some example python code that uses the TAMS API by @philipnbbc in #89
• api: An empty timerange filters flows with no content by @philipnbbc in #93
• api: move string-only JSON examples to the spec. YAML by @philipnbbc in #95
• app note: document tags used in AWS opensource CNAP impl by @philipnbbc in #94
• Add flow property updates ADR and specification extensions by @philipnbbc in #91
• Remove some copy-paste errors by @AndrewGibb in #92
• Fully define the Timestamp and TimeRange in the spec by @philipnbbc in #96
• Using flow segment timeranges and related spec updates by @philipnbbc in #97
• adr: add flow bit rate property definitions ADR by @philipnbbc in #86
• Remove ambiguity in re-used collection-item description by @j616 in #98
• Add assumed default to sample_offset by @j616 in #99
• Update PR template by @j616 in #100
• Improve documentation regarding instantaneous TimeRanges by @j616 in #101
• Flag that instantaneous TimeRanges can't use exclusive markers by @j616 in #102
• Fix commit check checkout ref by @philipnbbc in #103
• Add ADR for a query option to filter get_urls by @philipnbbc in #88
• Add a missing 403 by @j616 in #106
• Fix various snags with example scripts by @samdbmg in #107
• icla: Remove typo by @samdbmg in #109
• ADR: Add Source edit by reference endpoints by @samdbmg in #90
• example: Add interval edit script by @samdbmg in #108
• examples/outgest_file: Fix segment timerange check by @philipnbbc in #110
• Updates to Webhook events and filtering by @philipnbbc in #105
• example: Fix bug in timeshift calc by @samdbmg in #112
• Add Appnotes describing external references and using OpenTimelineIO by @samdbmg in #104

New Contributors

• @chalford made their first contribution in #87

Full Changelog: 5.1...6.0

5.1

What's Changed

• gha: trigger CI workflow after release to update API docs by @philipnbbc in #71
• api: provide consistent names for endpoints using summary property by @philipnbbc in #70
• Add supporting documentation index by @j616 in #73
• Add missing flow filter for multi essence and add format filter for sources by @philipnbbc in #74
• api: add words to flow segment POSTs related to overlaps by @philipnbbc in #76
• Consistent naming and description of creating or updating metadata by @philipnbbc in #77
• api: allow flow segment paging using opaque key by @philipnbbc in #75
• Remove unneeded 400 "Invalid query options" error by @j616 in #79
• Add missing headers to HEAD requests by @j616 in #80
• Add flow label endpoint by @j616 in #81
• Add ADR and appnote specifying get_urls label format by @j616 in #72
• Fix tag deleted descriptions by @j616 in #82
• Bump API version in readme and examples by @j616 in #83

Full Changelog: 5.0...5.1

5.0

What's Changed

• Add app note regarding using tams for data by @j616 in #52
• AN-0002 First Draft by @C-Lunn in #50
• Add app note regarding tag names by @j616 in #53
• Add application note regarding independently decodable segments by @j616 in #54
• Upload multiple API version renders by @j616 in #55
• Update documentation links to use new versioned documentation URLs by @j616 in #56
• Add ADR for checksum and filesize metadata by @j616 in #45
• Mapping to segment container tracks by @philipnbbc in #46
• Replace "Flow Deletion Request" in description with "Flow Delete Request" by @j616 in #57
• Fix typo in fix to typo by @j616 in #58
• api: mention flow container not set in 400 error descriptions by @philipnbbc in #59
• Add missing 403 responses related to ADR-0005 by @j616 in #61
• Add a note on API version compatibility to App Note 0006 by @j616 in #63
• Fix the container mapping JSON schema pattern for SMPTE UMID by @philipnbbc in #65
• Audit of HTTP responses and schemas by @j616 in #64
• ADR: Split service version parameter into separate api_version and service_version by @j616 in #62
• Rename "modified_by" properties to "updated_by" in Source and Flow schemas by @robwadge in #60
• api: rename modified_by to updated_by in examples by @philipnbbc in #67
• appnote: add populating source metadata app note by @philipnbbc in #66
• Add appnote 0008 on timestamps in TAMS by @robwadge in #68
• Update docs links to point to v5 release by @samdbmg in #69

New Contributors

• @C-Lunn made their first contribution in #50

Full Changelog: 4.0...5.0

4.0

What's Changed

• Describe Flow and media timelines by @samdbmg in #30
• README: Add references to Timestamp and TimeRange string patterns by @philipnbbc in #31
• Make clear that segments cannot overlap by @samdbmg in #32
• Add pagination of listing endpoints by @samdbmg in #33
• Add flow collections to the API by @robwadge in #35
• Random object IDs ADR and implementation by @philipnbbc in #34
• adr: Update random-storage-object-ids ADR status to accepted by @philipnbbc in #38
• Clarify that flow timeline is presentation timeline by @samdbmg in #37
• Clarify expectations of Flow Segment get_url by @samdbmg in #36
• Add event stream by @samdbmg in #39
• Basic Application Notes by @AndrewGibb in #40
• Improve descriptions of flow parameters by @j616 in #41
• Minor tweak to pixel_aspect_ratio description based on feedback by @j616 in #42
• Restructure docs directory by @philipnbbc in #43
• Add appnote 0001 - multi-mono-essence-flows-sources by @robwadge in #44
• adr: Fix status of ADRs that were accepted by @philipnbbc in #48
• Add missing example for multi-essence Sources by @robwadge in #49
• ADR: Restrict direct Source modification by @j616 in #47
• Modify the webhooks api by @philipnbbc in #51

New Contributors

• @AndrewGibb made their first contribution in #40

Full Changelog: 3.0...4.0

3.0

What's Changed

• Expand modified_by and created_by metadata by @j616 in #17
• Add .github codeowners file by @GeorginaShippey in #20
• Clarify Flow Segment in README by @GeorginaShippey in #23
• Add release tooling by @j616 in #26
• Consolidate timerange naming by @philipnbbc in #27
• Add Sources to API by @samdbmg in #18
• Indicate that timestamps are managed by the API server and ignored on PUT by @samdbmg in #19
• adr: Add non-permanent deletion ADR proposal by @samdbmg in #21
• Move Flow type-specific properties down into a sub-property by @samdbmg in #28
• adr: ancestry relationships by @philipnbbc in #22
• adr: Add a Flow update status ADR by @philipnbbc in #25
• adr: Add a Flow read-write permissions ADR by @philipnbbc in #24
• Clarify what a sample is for FlowSegment sample_offset/count by @philipnbbc in #29

New Contributors

• @GeorginaShippey made their first contribution in #20

Full Changelog: 2.0...3.0

2.0

What's Changed

• Add initial API by @samdbmg in #1
• Improve CI pipeline by @samdbmg in #2
• Rework example with real links by @samdbmg in #3
• Update timestamp and timerange types to use string patterns by @philipnbbc in #4
• Allow negative flow timeranges by @philipnbbc in #5
• Improve description of object re-use by @samdbmg in #6
• Add commit check workflow by @j616 in #10
• Expand Flow examples by @samdbmg in #7
• Switch to Stoplight Elements for docs render by @samdbmg in #8
• Make timerange more prominent in docs by @samdbmg in #9
• Describe flow segment timing adjustments when GETting by @philipnbbc in #11
• Add API Versioning section to README by @philipnbbc in #12
• Bump version to 2.0 by @philipnbbc in #13
• Add ADR folder structure and templates by @samdbmg in #15
• Add ADR folder structure, templates and initial ADR doc by @robwadge in #14
• Add CI linting for Markdown files by @samdbmg in #16

New Contributors

• @samdbmg made their first contribution in #1
• @philipnbbc made their first contribution in #4
• @robwadge made their first contribution in #14

Full Changelog: https://github.com/bbc/tams/commits/2.0