dblk / shottower

An open source, self-hosted implementation of the Shotstack API backend

ShotTower

An open source, self-hosted implementation of the Shotstack backend server.

Join our Discord server for a chat.

What is ShotStack

ShotStack is a video editing API that allow to build dynamic Video Applications at Scale.

Everything in ShotStack is Open Source, except the Dashboard and the backend server.

The backend server translate JSON to FFMPEG commands and serve the result.

Design goal

shottower aims to implement a self-hosted, open source alternative to the Shotstack backend server. shottower has a narrower scope and are not built for heavy transcode (but pull request are welcome!).

shottower uses terms that maps to Shotstack's API, consult the glossary for explanations.

Support

If you like shottower and find it useful, there is a sponsorship and donation buttons available in the repo.

If you would like to sponsor features, bugs or prioritization, reach out to one of the maintainers.

Features (Basic + Exclusive 😎)

• "Basic" (Track, Clip, VideoAsset, ...) support of Shotstack's features (See bellow for progress)
  • Use only the stage endpoint value until all features are implemented (See #1 for multiple endpoint handling)
• 😎 Possible to burn subtitle into video clip
• 😎 Allow to use local file from url filed (file:///Users/dblk/clips/my_asset)
• 😎 Add an endpoint /dl/{version}/renders/:id to download renders (instead of cdn/s3)
• 😎 Add other values for resolution (360, 480, 540, 720) all with default 25 fps.
• 😎 Add other values for output quality (highest, lowest).
• [Planned] Allow to use ftp file from url filed (ftp://user:[email protected]/mypath/my_asset)
• [Planned] Add destination to Youtube

Shotstack implementation progress

In the following matrix, there is only components than their implementation have been started.
At the end of the road this section should either disappear or be full of Yes 😇.

Component	Property	Implemented	Comment
Timeline	soundtrack	Not yet
Timeline	background	Yes ✅
Timeline	fonts	Not yet
Timeline	tracks	Yes ✅
Timeline	cache	Yes ✅
Track ✅	all ✅	Yes ✅
Clip	asset	Partial 🛠	Only VideoAsset & ImageAsset are handled
Clip	start	Yes ✅
Clip	length	Yes ✅
Clip	fit	Not yet
Clip	scale	Yes ✅
Clip	position	Yes ✅
Clip	offset	Not yet
Clip	transition	Not yet
Clip	effect	Not yet
Clip	filter	Not yet
Clip	opacity	Not yet
Clip	transform	Not yet
Clip [VideoAsset]	all ✅	Yes ✅
Clip [ImageAsset]	all ✅	Yes ✅
Clip [TitleAsset]	all	Not yet
Clip [HTMLAsset]	all	Not yet
Clip [AudioAsset]	src	Partial 🛠	Download asset only
Clip [AudioAsset]	trim	Not yet
Clip [AudioAsset]	volume	Not yet
Clip [AudioAsset]	effect	Not yet
Clip [LumaAsset]	src	Partial 🛠	Download asset only
Clip [LumaAsset]	trim	Not yet
Output	format	Partial 🛠	Only mp4 & gif at the moment
Output	resolution	Yes ✅
Output	aspectRatio	Not yet
Output	size	Yes ✅
Output	fps	Yes ✅
Output	scaleTo	Not yet
Output	quality	Yes ✅
Output	repeat	Yes ✅
Output	range	Not yet
Output	poster	Not yet
Output	thumbnail	Not yet
Output	destinations	Not yet
Callback		Yes ✅

Endpoint implementation

There are several endpoints that are available but not all of them are implemented.

Category	Endpoint Description	Status	Comment
Edit	Render asset	Yes ✅
Edit	Get Render Status	Partial 🛠	Missing real owner
Edit	Create Template	Not yet
Edit	List Template	Not yet
Edit	Retrieve Template	Not yet
Edit	Update Template	Not yet
Edit	Delete Template	Not yet
Edit	Render Template	Not yet
Edit	Inspect Media	Not yet
Serve	Get Asset	Partial 🛠
Serve	Delete Asset	Not yet
Serve	Get Asset by Render ID	Not yet

Running shottower

Please have a look at the documentation under docs/.

Disclaimer

1. We have nothing to do with shotstack
2. The purpose of ShotTower is maintaining a working, self-hosted Shotstack api compatible backend.

Contributing

To contribute to shottower you would need the latest version of Go.

Code style

To ensure we have some consistency with contributions, this project has adopted linting and style/formatting rules:

The Go code is linted with golangci-lint.

Check out the .golangci.yml to see the specific configuration.

Commit message

To ensure, the changelog are well generated, please use prefix in your commit message as follow:

• feat, features, feature: For new features
• fix: For any fix
• doc, docs: For any update in documentation (README, etc...)

And if you really need to commit something that is not working wip ou test are your friends.

Install development tools

• Go 1.18
• FFMPEG (v5 or up)
• gifski (For high quality GIF)
• ginkgo
• golangci-lint
• (optional) I recommend using gow

Testing and building

To run the tests (solo execution):

ginkgo -r --randomize-all --randomize-suites --race --trace -cover

To run the tests during development:

ginkgo watch -r --randomize-all --race --trace

To build the program:

go build

Running the server

To run the server, follow these simple steps:

go run main.go

To run the server in a docker container

docker build --network=host -t shottower .

Once image is built use

docker run --rm -it shottower

Contributors

Rémy Boulanouar

shottower's Issues

Review json to struct

With the generation of the project (thx to openapi-generator) we have to patch the Structure for Asset to have a proper VideoAsset and ImageAsset.

This needs also to be done for Destinations (inside output).
Instead of doing it manually for each ressource and having two properties (like Asset and TypedAsset), it would be better uppon unmarshal to have directly the current value of TypedAsset.

The code to modify is in api_edit.go in function PostRender.

Review the dockerfile

The current Dockerfile was generated with openapi-generator and so handle only the binary.
However to work, we need to bundle ffmpeg inside the dockerfile.

We need to fix this!

Is soundtrack the only way to combine sound and image with this API?

Hi! I saw you didn't implement "soundtrack" yet. But is there any other way to create a video with 1 image + 1 sound track with your current version?

thank you

Implement a proper logging system

Log for now are not structured and need to be done in a better way.

I propose to use https://github.com/uber-go/zap for logs.

Add a config file for secrets, api key, etc.

I would like to be able to setup configuration for various objectives such as:

• Having Youtube apikey inside config
• Having the type of the endpoing (v1 vs stage)
• Have the domain from which we will serve the app
• Have the list of user and their apikey to secure a bit the api
• ...

To manage the configuration, we will use github.com/spf13/viper.