Request for a new API: Update captions by transcription ID

[yiyanglin98]

The current caption updating API in /api/Captions can only update a single caption line with one API call, which is insufficient for frontend issue #103 for two reasons.

1. Bulk editing of captions needs to update multiple caption lines (text, start time and end time) by transcription ID, with a single API call.
2. User should be able to upload new caption document by transcription ID.

Therefore, it would be great to have a new API that can do PUT requests by transcription ID, to update/create captions efficiently.

Specification:

• The API should take a transcription ID, an index of caption array in the transcription array (for instance, currently, index 0 is for English caption array in a transcription array), and an array of caption object. In the frontend, the form of the caption objects in the caption array should be:
  { begin: "00:00:00.0400000", end: "00:00:03.2400000", index: 1, id: "4d5a6020-2fb1-4dc3-93f8-4845bbc2c131", text: "Reflecting on what makes an activity or hobby or what" }

• Frontend will provide a complete array of caption object, including the objects that are not modified. Backend should modify the captions according to the input. For captions that are deleted, the index should be -1, and the backend should handle the change of index accordingly. For new insertion, an id for the caption line should be generated.

More spec will be added...

[angrave]

Agreed! How should it work? Replace only captions that are different?Or does the frontend only provide inserts? How are soft deletes handled? Some thought needs to be put into creating a spec for this. So why not draft what it should do...

[yiyanglin98]

Agreed! How should it work? Replace only captions that are different?Or does the frontend only provide inserts? How are soft deletes handled? Some thought needs to be put into creating a spec for this. So why not draft what it should do...

Sure. I will add more details in the next few days.

Also, I am not sure why soft deletion is necessary here. Is that for data recovery? Do we need to offer an interface for the users to undo their deletion? Or there are other purposes for soft deletion here, e.g. counting the deleted captions for some reason.

[angrave]

Undo. We actually want a full revision history not just soft delete: e.g. want to be able to review changes made by a particular (or all) contributors or changes since date. Be able roll-back or undo a set of changes.

Also changes in main transcription suggest where changes should be made in translations

[tdy]

Will WebVTT just piggyback off this API spec, or are there other needs/considerations for a WebVTT API?

[angrave]

Yes, WebVTT uploaded to the frontend could piggyback off this API. So the ability to upload a vtt into the frontend would be useful.

(However we will need to support extracting captions from mp4 / upstream sources - so I imagine the backend will need some native WebVTT support to.)