Peertube: Add a subtitles API

[roipoussiere]

A subtitles API, allowing users to import a subtitle for a given video via the PeerTube API, could have a significant impact in the PeerTube network accessibility, and some interesting projects could emerge.

For instance, with a such API we could imagine a web service dedicated to video captioning, on which PeerTube users subscribe, that:

1. listens for new videos via RSS feed;
2. automatically downloads any video posted by authenticated users;
3. generates draft subtitles with Mozilla's DeepSpeech among its CommonVoice datasets;
4. publishes them on the web platform;
5. lets the community peer-reviews new subtitles;
6. eventually deal with a Weblate server API to allow the community to translate subtitles in other languages;
7. send peer-reviewed subtitles to the PeerTube instance via the subtitles API, with the user token.

Here is a suggestion for a subtitles API specification:

• GET: Get a video subtitles file
  
  
  
  • parameters:
    
    
    
    
    
    • id (string): The video id or uuid;
    
    
    
    • language (string): the language code, as defined in ISO 639-1;
    
    
    
  
  
  • responses:
    
    
    
    
    
    • 200: successful operation;
    
    
    
    • 404: subtitle not found for the given video id and language;
    
    
    
  
  
• POST: Put a video subtitles file
  
  
  
  • parameters:
    
    
    
    
    
    • id (string): The video id or uuid;
    
    
    
    • language (string): the language code, as defined in ISO 639-1;
    
    
    
    • overwrite (boolean): if a subtitle already exist for the specified video id and language, the request return a 409 error (default to true);
    
    
    
  
  
  • responses:
    
    
    
    
    
    • 200: successful operation;
    
    
    
    • 404: subtitle not found for the given video id and language;
    
    
    
    • 409 (conflict): a subtitle already exist for the specified video id and language (only triggered if overwrite is set to true);
    
    
    
  
  
• DELETE: Remove a video subtitles file
  
  
  
  • parameters:
    
    
    
    
    
    • id (string): The video id or uuid;
    
    
    
    • language (string): the language code, as defined in ISO 639-1;
    
    
    
  
  
  • responses:
    
    
    
    
    
    • 204: successful operation;
    
    
    
    • 404: subtitle not found for the given video id and language.
    
    
    
  
  

[Booteille]

This could become a must-have once the plugin engine is done.

I guess a lot of developpers could rely on this API to offer different tools around this feature.

[Chocobozzz]

We have a subtitle API: https://github.com/Chocobozzz/PeerTube/blob/develop/server/controllers/api/videos/captions.ts#L22

But it's not documented yet.

[Chocobozzz]

Doc added in https://github.com/Chocobozzz/PeerTube/commit/67ae04a5e7e20554a30b22a02792045505ee2d35