ungive/video-conversion-service

Small service to convert remote videos from one format to another.

For a real-world use case example try Music Presence and play a song with TIDAL that has an animated cover image.

Supported conversions

Input	Output
mp4	gif
m3u8	gif

More to be added in the feature, if the need arises.

Features

• Authenticated token endpoint for use in private contexts and to prevent abuse
• Only converts videos from a known list of whitelisted server hostnames
• Conversion results are cached for a configurable amount of time
• Tokens expire after a configurable amount of time

For open todos for more features and improvements check TODO.md

API

The service exposes a very simple, authenticated HTTP API.

Creating a token

This endpoint creates a token which can be used to fetch the converted video. It accepts a URL to a remote video resource, the input format and the target output format and returns a temporary token which can be used with the /convert endpoint.

GET /token

Required headers:

• Authentication: Basic authentication with username and password

Required query parameters:

• url: The URL from which to fetch the video resource
• ifm: The input format of the this remote video resource
• ofm: The target output format to which to convert the video

Optional query parameters:

• pre: Whether to preload the conversion result in the background instead of downloading and starting conversion on the first request. If requests to the convert endpoint are delayed, setting this is recommended
• rts: Enables real-time streaming which limits the streaming framerate to the target output frame rate (see ofr). This reduces stress on the server and should be set, if possible.
• osz: The target output video size. If not specified, the original video size or the server's maximum output size is used, whichever is smaller
• ofr: The target output frame rate. If not specified, the original video frame rate or the server's maximum output frame rate is used, whichever is smaller
• out_gif_colors: Parameter specific for GIF output: Sets the number of colors to use. Useful to influence output size

Example request:

https://api.example.com/token?ifm=mp4&ofm=gif&url=https%3A%2F%2Fexample.com%2Fvideo.mp4

Successful response (status code 200):

{
  "url": "https://api.example.com/convert.gif?token=6lXiknBhnF1a7C3njKZDY3",
  "token": "6lXiknBhnF1a7C3njKZDY3",
  "expires": 1727727055,
  "key": {
    "url": "https://example.com/video.mp4",
    "ifm": "mp4",
    "ofm": "gif"
  }
}

Simply request the URL in the url field to fetch the converted video.

Error response:

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "information about what happened"
}

Fetching the converted video

This endpoint converts the resource for the given token to the target output format.

GET /convert[:ext]

Path parameters:

• :ext (optional): File extension to communicate the output format. This might be needed by consumers of the URl in some contexts (e.g. for the GIF to properly show in a Discord status). The extension must be identical to the output format ofm.

Required query parameters:

• token: The token from the /token endpoint

Example request:

https://api.example.com/convert.gif?token=6lXiknBhnF1a7C3njKZDY3

Response:

<binary>

The response contains the converted video in the requested output format.

---

License

Copyright (c) 2024 Jonas van den Berg
MIT License, see LICENSE for details