SponsorBlockServer: the crowdsourced ad-skip database behind a browser extension

A timestamp store, not an ad blocker

The confusion here is worth clearing up first. SponsorBlock itself is a browser extension that skips sponsored segments of YouTube videos. It works because anyone can submit the start and end time of a sponsored segment, and once one person submits that information, everyone else with the extension skips past it. That sharing is the whole design.

SponsorBlockServer is the server half of that arrangement. It is the component that holds the timing data and serves it to clients. It does not decide what is an ad, it does not block network requests, and it does not run in the browser. If you are looking for a general purpose ad blocker, this repository is the wrong project, because the useful part only works together with the separate client extension at github.com/ajayyy/SponsorBlock.

The people who want this server are the extension's users who want their own instance, and the researchers who want the dataset. The README makes the second case explicit, describing the hope that the data can be combined with other projects to train a neural network that predicts where sponsored segments occur.

Postgres or SQLite behind an Express API

The server is a Node.js application written in TypeScript, and the package manifest names the entry point as `src/index.ts`. The HTTP layer is Express, with `express-promise-router` for routing and `express-rate-limit` for throttling, which is a sensible pairing for a public write endpoint that accepts segment submissions from anyone.

Storage is pluggable between two relational backends. `pg` is in the dependency list for Postgres, and `better-sqlite3` is there for the embedded case. The README states it plainly: the project "uses a Postgres or Sqlite database to hold all the timing data". A fresh database is created automatically, and to start from existing data you place the database files in the `./databases` folder.

Two supporting pieces stand out. `redis` and `rate-limit-redis` are present, which means rate limiting can be shared across instances rather than kept in process memory, and `lru-cache` plus `lz4-napi` suggest a compression and eviction layer for hot data. `cron` points to scheduled background work, and `axios` and `form-data` cover outbound HTTP calls. The schema itself is documented separately in DatabaseSchema.md, and the API reference lives at the SponsorBlock wiki.

The public database dump and its non-commercial licence

This is the detail that most affects whether you can use the project for anything commercial. The database is made publicly downloadable at https://sponsor.ajay.app/database, and the README gives a plain reason: making the data available is the mechanism that keeps the project from dying, since the value of a crowdsourced dataset collapses if contributors cannot see what they contributed.

The terms are not permissive. The database is under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 licence unless you get explicit permission from the maintainer. Two consequences follow. The server code is AGPL-3.0-only, so a modified server you expose to users carries network copyleft obligations. The dataset is non-commercial, so a company that wants to train a commercial model on sponsor timings cannot rely on the public dump and needs that explicit permission.

The README also mentions arranging an archive.org copy if you want a backup of your own. Archives of the download are helpful for reproducibility, but they do not change who holds the rights to the data.

Running the server locally with npm

The build path is short because the project runs directly from TypeScript sources with `ts-node`. Clone the repository, install the dependencies, copy the example configuration, and you have a working process.

npm install

Next, rename `config.json.example` to `config.json` and fill in the parameters. The README flags one trap here: the comments in the example file must be removed, because comments are not supported in JSON. If you want to start from existing segment data, place the database files in the `./databases` folder before the first run, otherwise a fresh database is created.

Run the test suite, which compiles the project and then executes the test entry point:

npm test

That script is `npm run tsc && ts-node test/test.ts`, so a passing run means both the TypeScript compilation and the Mocha tests succeeded. When you change code, `npm run dev` starts nodemon and re-runs tests on every saved file, which is the loop the project expects for contributors. Finally, start the server itself with:

npm start

The manifest also exposes `npm run lint` for ESLint over `src` and `test`, and a `cover` script that wraps the tests in `nyc` for coverage reporting.

A Docker image that listens on 8080

For deployment there is a two-stage Dockerfile. The builder stage installs build dependencies with apk, copies the manifest, lockfile, `tsconfig.json` and `entrypoint.sh`, copies `src`, and runs `npm ci && npm run tsc`. The runtime stage is a separate Alpine image that copies the compiled `dist` output and `node_modules` from the builder, along with the SQL seed files from `databases/`.

The image ends with a fixed port and a shell entrypoint:

EXPOSE 8080
CMD ./entrypoint.sh

The runtime stage also adds `git` and `postgresql-client`, which are needed by the entrypoint for database initialisation. The manifest also provides two convenience scripts that spin up backing services for development, one for Postgres on port 5432 and one for Redis on port 6379 with persistence disabled.

npm run postgres:docker

Run that and you get a Postgres instance with the CI credentials baked into the script, useful for exercising the `pg` path locally. The Redis equivalent, `npm run redis:docker`, starts a Redis with `--save '' --appendonly no`, so nothing survives a restart and the instance is purely a rate limit and cache layer for the running server.

Recent commits against 2019 release tags

The maintenance picture needs a careful reading. The repository is not archived, and the last push was on 2026-09-17, so work is still landing on the default branch, master. The visible releases, on the other hand, are old: 1.0.34 from 2019-08-13, 1.0.31 from 2019-08-12, and v1.0.21 from 2019-07-30. The manifest version field still reads `0.1.0`, which tells you the published package version and the tag history are two different things.

The dependency list is the more telling signal about the current state. `axios` at `^1.13.6` and `express` at `^4.22.1` are recent releases, `better-sqlite3` at `^11.2.1` is a modern major, and the Docker image builds on `node:24-alpine`. The `redis` client is at `^4.6.13` while `rate-limit-redis` is still at `^3.0.1`. Those version constraints describe a codebase that has been kept current even though the release tags have not been republished since 2019.

The practical consequence: do not plan an upgrade path around those tags. Clone the branch, read the dependency list, and pin what you actually deploy.

Editorial conclusion

Adopt SponsorBlockServer if you want to run the segment database yourself, contribute segment data to the public instance, or train a model on sponsor timings, and if you are comfortable with AGPL-3.0-only terms and a non-commercial database licence. Do not adopt it as a general ad-blocking product: it holds timestamps, not filters, and it depends on the separate browser extension for the user-facing part. Before running your own instance, verify the config.json parameters, confirm whether the public database dump licence covers your intended use, and check the schema in DatabaseSchema.md against the Postgres and SQLite backends you plan to use.

Frequently asked questions

Official sources

1. ajayyy/SponsorBlockServer on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases