diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 2a4b777e..21456120 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -24,13 +24,7 @@ services:
env_file: config.env
environment:
- REDIS_HOST=superstreamer-redis
- - REDIS_PORT=6379
- DATABASE_URI=postgresql://postgres:sprs@superstreamer-postgres/sprs
- - S3_ENDPOINT=${S3_ENDPOINT}
- - S3_REGION=${S3_REGION}
- - S3_ACCESS_KEY=${S3_ACCESS_KEY}
- - S3_SECRET_KEY=${S3_SECRET_KEY}
- - S3_BUCKET=${S3_BUCKET}
superstreamer-stitcher:
image: "superstreamerapp/stitcher:alpha"
@@ -42,14 +36,8 @@ services:
env_file: config.env
environment:
- REDIS_HOST=superstreamer-redis
- - REDIS_PORT=6379
- PUBLIC_API_ENDPOINT=http://localhost:52001
- PUBLIC_STITCHER_ENDPOINT=http://localhost:52002
- - S3_ENDPOINT=${S3_ENDPOINT}
- - S3_REGION=${S3_REGION}
- - S3_ACCESS_KEY=${S3_ACCESS_KEY}
- - S3_SECRET_KEY=${S3_SECRET_KEY}
- - S3_BUCKET=${S3_BUCKET}
superstreamer-artisan:
image: "superstreamerapp/artisan:alpha"
@@ -59,12 +47,6 @@ services:
env_file: config.env
environment:
- REDIS_HOST=superstreamer-redis
- - REDIS_PORT=6379
- - S3_ENDPOINT=${S3_ENDPOINT}
- - S3_REGION=${S3_REGION}
- - S3_ACCESS_KEY=${S3_ACCESS_KEY}
- - S3_SECRET_KEY=${S3_SECRET_KEY}
- - S3_BUCKET=${S3_BUCKET}
superstreamer-redis:
image: redis/redis-stack-server:7.2.0-v6
diff --git a/docker/minio/minio.env b/docker/integrations/minio/config.env.example
similarity index 54%
rename from docker/minio/minio.env
rename to docker/integrations/minio/config.env.example
index 8bb9ce23..271b9c73 100644
--- a/docker/minio/minio.env
+++ b/docker/integrations/minio/config.env.example
@@ -1,6 +1,6 @@
# MinIO Configuration
S3_ENDPOINT=http://superstreamer-minio:9000
S3_REGION=us-east-1
-S3_ACCESS_KEY=minioadmin
-S3_SECRET_KEY=minioadmin
-S3_BUCKET=superstreamer
\ No newline at end of file
+S3_ACCESS_KEY=sprs
+S3_SECRET_KEY=sprs
+S3_BUCKET=sprs
\ No newline at end of file
diff --git a/docker/minio/docker-compose.minio.yml b/docker/integrations/minio/docker-compose.yml
similarity index 66%
rename from docker/minio/docker-compose.minio.yml
rename to docker/integrations/minio/docker-compose.yml
index 716e90ad..3c0f0910 100644
--- a/docker/minio/docker-compose.minio.yml
+++ b/docker/integrations/minio/docker-compose.yml
@@ -7,12 +7,12 @@ services:
superstreamer-minio:
image: quay.io/minio/minio
environment:
- MINIO_ROOT_USER: minioadmin
- MINIO_ROOT_PASSWORD: minioadmin
+ MINIO_ROOT_USER: sprs
+ MINIO_ROOT_PASSWORD: sprs
command: server /data --console-address ":9001"
ports:
- - "9000:9000" # API
- - "9001:9001" # Console
+ - "9000:9000"
+ - "9001:9001"
volumes:
- superstreamer_minio_data:/data
healthcheck:
@@ -21,14 +21,14 @@ services:
timeout: 5s
retries: 5
- createbuckets:
+ superstreamer-minio-bootstrap:
image: minio/mc
depends_on:
superstreamer-minio:
condition: service_healthy
entrypoint: >
/bin/sh -c "
- mc alias set myminio http://superstreamer-minio:9000 minioadmin minioadmin;
- mc mb myminio/superstreamer;
+ mc alias set myminio http://superstreamer-minio:9000 sprs sprs;
+ mc mb myminio/sprs;
exit 0;
"
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 1db6258f..a0bd967a 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -39,7 +39,7 @@ export default defineConfig({
provider: "algolia",
options: {
appId: "4JIX5YPW7R",
- apiKey: "004a506c5ecd75d2a16d12feefc7af58",
+ apiKey: "97be940a67cc7ae000c625203b1c51f1",
indexName: "matvp91io",
},
},
@@ -108,35 +108,46 @@ function sidebarGuide() {
text: "Getting Started",
link: "getting-started",
},
- {
- text: "Packages",
- link: "packages",
- },
- {
- text: "Learning",
- link: "learning",
- },
],
},
{
- text: "Features",
+ text: "Project",
items: [
{
- text: "Video processing",
- link: "video-processing",
+ text: "What's included",
+ link: "whats-included",
},
{
- text: "Playlist manipulation",
- link: "playlist-manipulation",
+ text: "Building blocks",
+ link: "building-blocks",
+ items: [
+ {
+ text: "Video processing",
+ link: "video-processing",
+ },
+ {
+ text: "Video personalization",
+ link: "video-personalization",
+ },
+ {
+ text: "Player",
+ link: "player",
+ },
+ ],
},
{
- text: "Player",
- link: "player",
- },
- {
- text: "Dashboard",
- link: "dashboard",
- },
+ text: "Tutorials",
+ items: [
+ {
+ text: "Play adaptive video",
+ link: "tutorials/play-adaptive-video"
+ },
+ {
+ text: "Add bumper like Netflix",
+ link: "tutorials/add-bumper-like-netflix"
+ }
+ ]
+ }
],
},
{
@@ -147,8 +158,8 @@ function sidebarGuide() {
link: "contribute",
},
{
- text: "Credits",
- link: "credits",
+ text: "Thank you",
+ link: "thank-you",
},
],
},
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index e9943221..cdfe6980 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -4,9 +4,17 @@
--vp-c-brand-3: #ff7400;
--vp-home-hero-name-color: transparent;
- --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #ff4d00 30%, #ff9a00);
-
- --vp-home-hero-image-background-image: linear-gradient(-45deg, rgba(255, 77, 0, .2) 40%, rgba(255, 154, 0, .2) 40%);
+ --vp-home-hero-name-background: -webkit-linear-gradient(
+ 120deg,
+ #ff4d00 30%,
+ #ff9a00
+ );
+
+ --vp-home-hero-image-background-image: linear-gradient(
+ -45deg,
+ rgba(255, 77, 0, 0.2) 40%,
+ rgba(255, 154, 0, 0.2) 40%
+ );
--vp-home-hero-image-filter: blur(44px);
}
@@ -35,10 +43,12 @@
max-width: 160px;
}
-.video {
- border-radius: 12px;
- overflow: hidden;
- box-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
+.schema {
+ margin: 4em 0;
+}
+
+.framed {
+ border-radius: 1rem;
}
.package {
@@ -65,20 +75,39 @@
border-left: 1px solid var(--vp-c-divider);
}
-.schema {
- margin: 3rem auto;
+.package div {
+ margin-left: 2rem;
+}
+
+.video {
+ border-radius: 1rem;
width: 100%;
}
-.schema-stitcher {
- max-width: 400px;
+.number {
+ width: 1.5rem;
+ height: 1.5rem;
+ font-size: 0.85rem;
+ color: #ffffff;
+ background-color: #000000;
+ border-radius: 100%;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ margin-right: 0.5rem;
+ text-align: center;
+ font-weight: bold;
}
-.schema-dashboard {
- max-width: 300px;
+h1,
+h2,
+h3 {
+ display: flex;
+ align-items: center;
}
-.details.minimal {
- background-color: transparent;
- padding: 0;
-}
\ No newline at end of file
+.image-rounded {
+ border-radius: 1rem;
+ width: 100%;
+ border: 2px solid #f1f1f1;
+}
diff --git a/docs/guide/building-blocks.md b/docs/guide/building-blocks.md
new file mode 100644
index 00000000..bb25fa62
--- /dev/null
+++ b/docs/guide/building-blocks.md
@@ -0,0 +1,5 @@
+# Building blocks
+
+Getting the bigger picture from a high-level perspective can be challenging, but we'll do our best to guide you through how the different building blocks come together.
+
+Ideally, Superstreamer provides tools that cover everything from input source files, like an MP4, all the way to playback, such as a player embedded in a page. However, you're free to choose the tools that best fit your use case and extend them with Superstreamer's features as needed.
\ No newline at end of file
diff --git a/docs/guide/contribute.md b/docs/guide/contribute.md
index 8b6d3ee1..9fb12ea6 100644
--- a/docs/guide/contribute.md
+++ b/docs/guide/contribute.md
@@ -2,41 +2,6 @@
This is a living document about notes from contributors. If you'd like to contribute yourself, feel free to read through this info first.
-## Project structure
-
-Superstreamer consists of multiple packages, each serve their own purpose. This is particularly handy when you want to scale. You could easily run a package on multiple machines, such as Artisan.
-
-
-
-
- | Package |
- Description |
-
-
-
-
- | App |
- A front-end that uses the API and visualizes running jobs. |
-
-
- | API |
- Used to interact with the system. Start transcode jobs, get a list of pending jobs, and much more. |
-
-
- | Artisan |
- The main job runner, can be run on as many machines as you like. |
-
-
- | Stitcher |
- An HLS playlist proxy for on the fly manipulation, such as interstitials insertion and resolution filtering. |
-
-
- | Player |
- An easy to use HLS.js wrapper and UI built with React. |
-
-
-
-
## Running jobs
We rely on [BullMQ](https://docs.bullmq.io/), a queue job runner, to define transcode, package and ffmpeg jobs. Eg; take the `/transcode` endpoint, this will push a job to the Redis queue. Artisan constantly monitors the Redis queue for pending work, and when there is a pending job available, it'll start working on that. When finished, it'll update the job that it finished.
diff --git a/docs/guide/credits.md b/docs/guide/credits.md
deleted file mode 100644
index 47811b60..00000000
--- a/docs/guide/credits.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Credits
-
-Superstreamer wouldn't be here without the awesome help from others! There are some killer projects out there innovating the video industry step by step. Big thanks for all your amazing work β we definitely couldn't have pulled this off without you and a ton of coffee!
-
-- The people behind [HLS.js](https://github.com/video-dev/hls.js/), past and present contributors.
-- The people behind [FFmpeg](https://www.ffmpeg.org/), without y'all, video today would be as real as unicorns.
-- The [Shaka Project](https://github.com/shaka-project).
-- A special shout to Robert Walch for answering so many of my (stupid) questions.
-- 
for the most epic CDN in the world.
-
App 
-
- A Single Page Application (SPA) used to interact with the API or start a session on the Stitcher service.
-
-
-
API 
-
- The API serves as the primary interface for interacting with Superstreamer, such as start tasks like transcoding or packaging jobs. A swagger page is exposed on the /swagger endpoint.
-
-
-
Artisan 
-
- The actual job runners, these run in the background and consume whatever job API has scheduled next. Artisan instructs `ffmpeg` to run, or packages a previously transcoded asset to an HLS playlist and syncs it all to S3.
-
-
-
Stitcher 
-
- Also referred to as a "playlist manipulator," Stitcher can create a session for each user and generate a custom HLS playlist tailored to their needs, including resolution filtering and the addition of bumpers or linear ads. The stitcher has its own API. A swagger page is exposed on the /swagger endpoint.
-
-
-
Player 
-
- The player facade simplifies HLS.js with an intuitive API for building the player. It offers player-friendly methods, supports plugins, and provides React hooks for efficient state management.
-
-
+
+{width=100px}
+
+{width=80px}
+
+{width=140px}
+
+{width=120px}
+
+{width=120px}
+
+{width=60px}
+
+{width=80px}
+
+
+
+
+
+- A special shout to Robert Walch for answering so many of my questions.
\ No newline at end of file
diff --git a/docs/guide/tutorials/add-bumper-like-netflix.md b/docs/guide/tutorials/add-bumper-like-netflix.md
new file mode 100644
index 00000000..b1598e18
--- /dev/null
+++ b/docs/guide/tutorials/add-bumper-like-netflix.md
@@ -0,0 +1,27 @@
+# Add bumper like Netflix
+
+## 1 Prepare our sources
+
+We've got the following sources transcoded and packaged:
+
+- Big Buck Bunny, see [Play adaptive video](/guide/tutorials/play-adaptive-video),
+
+ with UUID `56bfe1d6-ce51-4a28-b688-bc64a89508b6`.
+
+- A Netflix bumper (for illustrational purpose),
+
+ with UUID `929045c6-13a2-417d-8df0-5a756766172d`.
+
+Make sure to check [Video personalization](/guide/video-personalization) first.
+
+## 2 Stitch bumper before content
+
+We're going to use Stitcher to create us a personalized playlist, with both our videos combined.
+
+
+
+## 3 Play our personalized HLS playlist
+
+We'll use the player to load our new HLS playlist URL.
+
+
\ No newline at end of file
diff --git a/docs/guide/tutorials/play-adaptive-video.md b/docs/guide/tutorials/play-adaptive-video.md
new file mode 100644
index 00000000..717efc5b
--- /dev/null
+++ b/docs/guide/tutorials/play-adaptive-video.md
@@ -0,0 +1,63 @@
+# Play adaptive video
+
+Adaptive video, or adaptive bitrate streaming, is a technique that adjusts the quality of a video stream based on the viewer's network conditions and device capabilities.
+
+Instead of a single video file, adaptive streaming involves multiple versions of the same video at different quality levels.
+
+In order to do this, we'll have to create an HLS playlist from our video file.
+
+In this tutorial, we'll use the dashboard as a way to inspect what Superstreamer does. When you use our Docker images, the dashboard is hosted on `http://localhost:52000` by default.
+
+## 1 Upload our source
+
+We'll take this Big Buck Bunny video and upload it somewhere. This could either be on the S3 configured in Superstreamer or have it accessible through http(s).
+
+
+
+For this tutorial, we'll upload it to the S3 configured in Superstreamer' `config.env` file. We have it available as `s3://input_bbb.mp4`.
+
+## 2 Transcode to multiple qualities
+
+We'll transcode our Big Buck Bunny video and produce the following streams:
+
+- 720 in height.
+- 480 in height.
+- An audio track with language "eng" (English).
+
+
+
+If you want fine grained control, take a look at the API docs in order to specify a different bitrate or framerate. For now, we'll rely on the sane defaults provided by Superstreamer.
+
+Once the transcode job is finished, a unique UUID is assigned to this asset. In our example, Superstreamer created the new UUID `56bfe1d6-ce51-4a28-b688-bc64a89508b6`. From now on, if we want to do something with this transcode result, we'll simply provide this id.
+
+
+
+We'll now see in the Storage tab that Superstreamer produced several video and audio tracks.
+
+## 3 Package to HLS
+
+At this stage, these separate tracks don't hold much value for a player. What we need is for video players to switch between different qualities based on the user's bandwidth or preferences. To achieve this, we'll extract segments β small chunks of videoβfor each stream and package them into an HLS playlist.
+
+
+
+Packaging is straightforward: just grab the UUID from the transcode job (`56bfe1d6-ce51-4a28-b688-bc64a89508b6`) and pass it to the package endpoint. This triggers a packaging job behind the scenes.
+
+## 4 Check HLS playlist in storage
+
+If we'd like to know what's being produced, we can go back to the Storage tab and inspect the `/package/56bfe1d6-ce51-4a28-b688-bc64a89508b6` folder.
+
+
+
+Notice how we transformed a single MP4 video file into a collection of segments, all referenced by an HLS playlist. This playlist is ready to be played by any HLS-compliant player.
+
+## 5 Play our HLS playlist
+
+
+
+Superstreamer comes with a player page where you can easily test your videos. In our example, the HLS playlist is available at:
+
+```sh
+
+https://{PUBLIC_S3_ENDPOINT}/package/56bfe1d6-ce51-4a28-b688-bc64a89508b6/master.m3u8
+
+```
\ No newline at end of file
diff --git a/docs/guide/playlist-manipulation.md b/docs/guide/video-personalization.md
similarity index 55%
rename from docs/guide/playlist-manipulation.md
rename to docs/guide/video-personalization.md
index ac2b29a2..52e1bbb4 100644
--- a/docs/guide/playlist-manipulation.md
+++ b/docs/guide/video-personalization.md
@@ -1,43 +1,68 @@
---
-outline: [1,4]
+outline: [2,4]
---
-# Playlist manipulation
+# Video personalisation
-Stitcher is a playlist manipulator that can insert HLS interstitials on-the-fly.
+Superstreamer comes with a separate project named Stitcher, an HLS playlist manipulator that can insert interstitials on-the-fly. You can use Stitcher to set individual quality limits for each user or to insert advertisements into your content.
+
+Make sure you read the [Video processing](/guide/video-processing) page first. In order to stitch playlists together, we must first make sure we have our video files processed and available as HLS playlists.
+
+## Terminology
+
+Before we dive in, let's cover some basic terminology. We'll keep this brief, but if you're eager to learn more about video, check out [howvideo.works](https://howvideo.works/). They provide a great explanation of the video delivery process from source to playback.
+
+- Stitching
+
+ Stitching is the real-time manipulation of a video stream, where multiple HLS playlists are combined and adjusted on the fly. It allows for adding bumpers or ads seamlessly.
+
+- HLS
+
+ HLS (HTTP Live Streaming) is a protocol that splits video into small chunks and delivers them over HTTP. For Superstreamer, we focus exclusively on using HLS for streaming.
+
+- Interstitial
+
+ An interstitial is a type of video segment inserted into an HLS playback session, usually serving as a mid-stream interruption for purposes like advertisements, informational messages, or promotional content.
## Use cases
-- Insert linear ads at given cue points, derived from a VMAP.
+- Insert linear ads at given cue points, derived from a VMAP (a spec compliant format that includes the positions of where ads should be in a video).
- Add a bumper playlist at the start of a playlist, like Netflix' intro. You wouldn't want to re-transcode an asset if a bumper changes.
- Filter a media playlist to exclude qualities, eg; free users can stream up to 720p.
## Create a session
+To personalize a playback session, begin by creating a session for a specific user. This requires a `POST` request, where the body includes parameters for Stitcher to generate a customized playlist in response.
+
+
+
+
-Video transcoding is the process of converting video, audio and text from one format to another. This involves changing the file's encoding to make it compatible with different devices, reduce its size, or adjust its quality.
+We'll begin by sending a `POST` request to the `/transcode` endpoint of our API. In this request, we'll specify the source files (our available inputs) and define the desired outputs β specifically, HD and Full HD video tracks, along with English audio.
-:::
-
-::: code-group
+```sh
+curl -X POST
+ "https://api.domain.com/transcode"
-```sh [Terminal]
-$ curl -X POST https://api-superstreamer.domain.com/transcode
- -H "Content-Type: application/json"
- -d "{body}"
```
-:::
-
-This is a body payload for the `BigBuckBunny.mp4` file we've uploaded to our S3 bucket, as specified in the config.env file. The source file contains a video and audio track. We've also uploaded a `BigBuckBunnyEng.vtt` file that contains the subtitles.
+::: code-group
-```json
+```json [Request]
{
- "inputs": [
- // Describe video input
+ "input": [
{
- "path": "s3://source/BigBuckBunny.mp4",
- "type": "video"
+ "type": "video",
+ "url": "https://domain.com/video.mp4"
},
- // Describe audio input
{
- "path": "s3://source/BigBuckBunny.mp4",
"type": "audio",
- "language": "eng",
- "channels": 2
- },
- // Describe text input
- {
- "path": "s3://source/BigBuckBunnyEng.vtt",
- "type": "text",
+ "url": "https://domain.com/video.mp4",
"language": "eng"
}
],
"streams": [
- // We'd like to produce a HEVC encoded video stream.
{
"type": "video",
- "codec": "hevc",
- "height": 720,
- "bitrate": 4000000,
- "framerate": 24
+ "codec": "h264",
+ "height": 1080
},
- // And an h264 encoded video stream, at a lower resolution.
{
"type": "video",
"codec": "h264",
- "height": 480,
- "bitrate": 1500000,
- "framerate": 24
+ "height": 720
},
- // We'd like to create an audio stream, aac codec with 2 channels.
- // If our source was 6 channels (surround), we'd be able to pass 6 here too.
{
"type": "audio",
"codec": "aac",
- "bitrate": 128000,
- "language": "eng",
- "channels": 2
- },
- // We want an "English" text track.
- {
- "type": "text",
"language": "eng"
}
- ],
- // We'll define the segment size upfront, this will be used for packaging purposes.
- "segmentSize": 2,
+ ]
}
```
-The result of the transcode job will be an `assetId`, this is a unique UUID that identifies a transcode result. From now on, we'll only work with this id. Eg; if you want to package this transcode result, all we'll have to do is provide this id.
+:::
-```json
+Under the hood, Superstreamer kicks off a transcode job to produce the output streams. Once completed, each job is assigned a unique UUID. For example, in this case, the UUID is `46169885-f274-43ad-ba59-a746d33304fd`.
+
+This request above will provide a response containing the jobId:
+
+::: code-group
+
+```json [Response]
{
- "assetId": "2d6e6c0e-07d9-48b1-8192-318f32a3b909"
+ "jobId": "transcode_46169885-f274-43ad-ba59-a746d33304fd"
}
```
-Let's quickly go over the steps that the transcode process did:
-
-- Download, or stream, the input file directly to ffmpeg.
-- Store the outcome on hard disk temporarily.
-- Upload the transcoded media file to S3.
+:::
-And it'll do these steps for each output stream separately. If you scale Artisan horizontally, it'll pick up each ffmpeg job individually across different machines and get to work.
+This UUID serves as a reference for the asset across all interactions with the Superstreamer API.
-That's great and all, but what do we do with the result of a transcode job? A transcode result is not playable by definition. We'll use the transcode result to package our asset into an HLS playlist.
+When the job is done, we have separate video tracks in various quality levels and a single audio track in English, exactly the result we were aiming for.
-## Start a package job
+## Start a package
-Now that we have transcoded our input file(s), we'll prepare them for streaming.
+Our video and audio tracks are stored as separate files. Let's package them into an HLS playlist, which players will use to determine what to load and at which resolution.
-::: tip
+
-Video packaging refers to the process of preparing a video file for delivery and consumption by users across different devices and platforms.
+We'll send a `POST` request to the `/package` endpoint of our API, and all we'll have to do is provide the assetId returned by our transcode job.
-:::
-
-We split the transcoding and packaging processes into two separate steps (API calls). This allows you to generate various packaging outputs from a single transcoding result. For instance, you can create both a DRM-protected and a standard HLS playlist from the same transcoded asset. By separating these steps, we avoid the need to re-transcode our assets, which is usually resource-intensive and can heavily utilize your CPU (and sometimes GPU). In contrast, packaging is a relatively light task.
+```sh
+curl -X POST
+ "https://api.domain.com/package"
+```
::: code-group
-```sh [Terminal]
-$ curl -X POST https://api-superstreamer.domain.com/package
- -H "Content-Type: application/json"
- -d "{body}"
+```json [Request]
+{
+ "assetId": "46169885-f274-43ad-ba59-a746d33304fd"
+}
```
:::
-All we'll have to do is instruct the packager to package a given `assetId`. When no transcode result is found for the given id, an error will be thrown.
+We'll check the dashboard app to check the status of our transcode job.
-```json
-{
- "assetId": "2d6e6c0e-07d9-48b1-8192-318f32a3b909"
-}
+And that's it. We now have an HLS playlist available on our S3 bucket.
+
+```
+https://cdn.domain.com/package/46169885-f274-43ad-ba59-a746d33304fd/master.m3u8
```
-A package job runs the following steps:
+## Start a pipeline
-- Download all transcode results from S3 to local hard disk.
-- Package all different streams into an HLS playlist.
-- Upload the playlists, and the segments, back to S3 in the `/package` folder.
+In earlier steps, we covered how to transcode and package your video file. With a pipeline job, these two steps can be combined into a single process.
-If you've properly configured config.env, your asset is now available for playback at the following URL:
+```sh
+curl -X POST
+ "https://api.domain.com/pipeline"
```
-{PUBLIC_S3_ENDPOINT}/package/2d6e6c0e-07d9-48b1-8192-318f32a3b909/hls/master.m3u8
+
+```json [Request]
+{
+ "input": [
+ {
+ "type": "video",
+ "url": "https://domain.com/video.mp4"
+ },
+ {
+ "type": "audio",
+ "url": "https://domain.com/video.mp4",
+ "language": "eng"
+ }
+ ],
+ "streams": [
+ {
+ "type": "video",
+ "codec": "h264",
+ "height": 1080
+ },
+ {
+ "type": "video",
+ "codec": "h264",
+ "height": 720
+ },
+ {
+ "type": "audio",
+ "codec": "aac",
+ "language": "eng"
+ }
+ ]
+}
```
-And tada, you now have a playable asset that can be played with HLS.js! π π₯³
-Give it a try and play your asset in the HLS.js demo page: https://hlsjs.video-dev.org/demo/
\ No newline at end of file
+The pipeline job generates a unique UUID, and once complete, your asset is instantly available as an HLS playlist β just as if you had packaged it manually.
\ No newline at end of file
diff --git a/docs/guide/what-is-superstreamer.md b/docs/guide/what-is-superstreamer.md
index 051d35b1..859386e3 100644
--- a/docs/guide/what-is-superstreamer.md
+++ b/docs/guide/what-is-superstreamer.md
@@ -1,105 +1,65 @@
# What is Superstreamer?
-Superstreamer is here to make video delivery simple. Imagine having everything you need in one platform β starting with your raw video, Superstreamer helps you transcode it, package it into HLS playlists, and upload it to S3 with ease. You can even create custom playlists for each viewer, adding bumpers, ads, or filters on the fly.
+Superstreamer is an open-source platform designed to simplify video delivery. It offers the tools you need to easily integrate high-quality video streaming into your applications.
-When it's time for your audience to watch, Superstreamer's elegant web player ensures your videos are delivered smoothly and look great on any device. It takes the hassle out of streaming, so viewers can enjoy your content without any interruptions.
+Our goal is to create a robust, flexible solution that empowers developers, hobbyists, and companies alike to focus on delivering amazing video experiences, similar to how Netflix, YouTube or Vimeo work.
-There are plenty of great video tools out there, but we saw a gap β a unified platform to bring all those tools together. Our mission with Superstreamer is to make video more accessible for developers, letting them focus on their projects without getting bogged down by the technical details.
+[Join our community](https://discord.gg/4hXgz9EsF4) and help us make video streaming more accessible together.
-::: info
-Can't wait? Head over to our [Getting Started](/guide/getting-started) page and jump right into it!
-:::
-
-::: tip
-
-Check out these cool screen recordings of the dashboard app! Click here to view them. The link will open in a new tab, so you won't lose your place.
-
-:::
-
-## How it works
-
-Everyone loves schemas, and we're no exception. Let's break down how Superstreamer works and how all the packages are interconnected.
-
-You've got an epic video file named Frames_Of_Thrones.mp4. It's hefty, and you want to deliver it to your audience with a seamless viewing experience, complete with subtitle options in various languages. Your goal is to provide the best possible experience for your viewers.
-
-### Transcode
-
-First, we'll take the source file and create several video streams, ranging from 480p to 1080p β like the options you see on YouTube. We'll also point the player to the audio track, which in this case is embedded in the MP4 file. To top it off, we'll include a couple of subtitle files.
+## Why?
-
+Delivering video is complicated because there are so many different ways to process, store, and deliver video content.
-
- Steps to take
+You have to deal with things like video quality, file sizes, compatibility across devices, and fast delivery speeds. Right now, there are lots of different tools and approaches, but they don't always work well together.
- 1. You send a transcode request to the API using your file or s3 URL as the input, along with a few output stream definitions.
- 2. The API will push a transcode job to Redis.
- 3. One, or multiple (if you're into scale), Artisan instances will grab jobs from Redis, and produce outputs streams locally.
- 4. Each Artisan instance will push their output stream to S3.
- 5. Finally, the API will assign a unique Asset ID to the process, allowing us to continue working with it.
-
+Our goal is to focus on just the important basics and make them work perfectly together, using the standards everyone already uses, so it's easier for everyone to create and watch videos.
-### Package
+::: details Our technical mantra
-So, we've taken our original video, sliced it up into different qualities, bitrates β event threw in some subtitles and a surround sound track for good measure. Awesome, right? Well... now we've got a bunch of separate files hanging out on S3. We need to bundle these up so the video player can actually make sense of the mess.
+If you're familiar with video engineering, the terms below might sound familiar. We aim to reduce the fragmentation in the field, and we believe we can excel by focusing on a select few aspects and perfecting them.
-
-
-
- Steps to take
-
- 1. You send a package request to the API with the Asset ID from the transcode process.
- 2. The API will push a package job to Redis.
- 3. An Artisan instance will download the transcoded files and generate an HLS playlist along with the video segments locally.
- 4. The HLS master playlist, media playlists and segments are uploaded to S3 with public permissions.
-
-
-### Play
-
-Alright, we've got our HLS playlist sitting in the S3 bucket. You could hit play and call it a day, sure, but where's the fun in that? Like, we've got this NotFlix bumper β _tuduuuum_ β and we want to slap it right in front of our Frames of Thrones masterpiece. So, what do we do? We transcode and package that bumper, then tell our stitcher to whip up a new playlist on the fly, combining our bumper with the main content. Boom β playlist magic! πͺ
+- HLS as a playlist format, with CMAF containered segments.
+- Inserting and playing other playlists, like ads, depends completely on HLS interstitials. Watch Apple's [Intertitials Intro](https://developer.apple.com/videos/play/wwdc2024/10114/#:~:text=With%20HLS%20interstitials%2C%20ads%20or,content's%20Program%2DDate%2DTime.) video announced at WWDC24.
+- No VAST on the client, ever. π
+- Don't reinvent the wheel β leverage the fantastic work of others. If that means making open-source contributions, we're all for it.
+:::
-
+## Building blocks
-
- Steps to take
+The project is made up of several building blocks, each designed to handle specific tasks in the video streaming process. It's important to know that you don't need to use everything β this isn't an all-or-nothing solution. We want to avoid vendor lock-in, so you're free to pick and choose the building blocks that best fit your needs.
- 1. You send a session request to the Sticher API, with the Asset ID from the transcode (or package, they're the same) process, along with your parameters (eg; ad insertion, bumper, ...)
- 2. Stitcher will prepare a unique playlist for this session, which the player downloads.
- 3. The player can now play the video, it will grab the rest (such as segments) from S3 directly.
-
+For example, you can use our tool for real-time video manipulation (like inserting a bumper or ads), while still transcoding and packaging your video files elsewhere, such as using [Mux](https://www.mux.com/) for those steps.
-### Monitor
+The flexibility is yours to create the workflow that works best for you.
-We'd like to keep an eye on what Superstreamer is up to behind the scenes. Don't worry, we've got a handy little app we call the dashboard. It's like a reality show for your jobs β complete with a list that shows all the action, including status updates and how long everything takes.
+## Use cases
-And if you're feeling ambitious and want to integrate Superstreamer into your own project (which, let's face it, if you're in the video biz, you absolutely should try), interacting with the API from your backend is a walk in the park.
+To users, video seems simple β it just plays, right? But delivering a smooth experience for every viewer is actually quite complex. Video isn't as straightforward as it appears. We're here to take care of the technical challenges and make video delivery easy for you.
-
+- Optimize for speed and quality
-## Developer Experience
+ Need your videos to load faster and look great? This tool makes sure your videos play quickly and at the best quality, no matter the device. If your viewers have slow internet, the [transcode tool](/guide/process#start-a-transcode) can adjust the video quality so it still plays smoothly without buffering.
-- **Simplified workflow**
+- Convert to different formats
- Handling video at scale involves multiple steps: ingesting source files, transcoding them into various formats, packaging for different devices, and ensuring smooth delivery. Superstreamer streamlines these steps into a unified workflow.
+ Want to play your video on any device? Our transcode tool changes your video to the right format so everyone can watch it, in different qualities depending on the viewer' bandwidth.
-- **Scalability**
+- Monetize your content
- Video platforms often need to serve content to large, diverse audiences, which requires infrastructure that can handle spikes in traffic and support multiple video formats. Superstreamer can be scaled horizontally due to a built-in queue / worker architecture and works great with any S3 compliant storage.
+ Our ad insertion tool lets you add ads at the perfect moment to earn revenue while keeping the viewer engaged.
-- **Customization and Personalization**
+- Package for streaming
- Modern video platforms often need to deliver personalized content, such as inserting targeted ads, bumpers, or even dynamically altering playlists based on user behavior. Superstreamer is built for these needs and can handle the real-time processing required to customize video streams.
+ Ready to show your video online? Our [package tool](/guide/process#create-a-package) packages your video so it streams smoothly to your viewers, no matter where they are.
-- **Cost Efficiency**
+- Create custom playlists
- Building and maintaining a full-scale video pipeline can be resource-intensive. Fortunately, Superstreamer isn't tied to a single vendor, allowing you the freedom to choose the most effective and cost-efficient strategies for your media setup.
+ Want to give your viewers a personalized video experience? Our [stitcher tool](/guide/stitch) lets you change the video order in real-time, so each viewer gets something unique.
-## Core Standards
+- Client streaming library
-We believe in sticking to the tried-and-true standards that make video delivery easier for everyone. By using common formats like H.264, HEVC, AAC, EC-3, ... and streaming methods like HLS, we make sure our platform works smoothly across all devices. When it comes to ads, we stick to IAB VAST for placements, which helps us connect easily with different advertising networks.
+ Need an easy way to work with [HLS.js](https://github.com/video-dev/hls.js)? Our player's facade makes it super simple to integrate streaming into your project, without dealing with complex video library code. Just focus on your content, and let the player handle the rest.
-Video is already a pretty fragmented space. By sticking to our standards, we aim to cut through that confusion and make things more straightforward. When you don't have to tackle everything at once, it's much easier to strive for perfection. That's why we made these thoughtful choices:
+- Player
-- HLS as a playlist format, with CMAF containered segments.
-- Inserting and playing other playlists, like ads, depends completely on [HLS interstitials](https://developer.apple.com/streaming/GettingStartedWithHLSInterstitials.pdf).
-- No VAST on the client, ever. π
-- Don't reinvent the wheel β leverage the fantastic work of others. If that means making open-source contributions, we're all for it.
\ No newline at end of file
+ Want a beautiful, modern video player? Our React component offers an eye-catching design and smooth functionality, giving your viewers an amazing experience.
\ No newline at end of file
diff --git a/docs/guide/whats-included.md b/docs/guide/whats-included.md
new file mode 100644
index 00000000..3fa8ea74
--- /dev/null
+++ b/docs/guide/whats-included.md
@@ -0,0 +1,53 @@
+# What's included
+
+Superstreamer is a monorepo, with multiple smaller projects inside. We'll provide a quick overview of the packages below to give you a sense of what each one does.
+
+
+
App
+
+ A Single Page Application (SPA) used to interact with the API or start a session on the Stitcher service.
+
+
+
+
+
+
API
+
+ The API serves as the primary interface for interacting with Superstreamer, such as start tasks like transcoding or packaging jobs. A swagger page is exposed on the /swagger endpoint.
+
+
+
+
+
+
Artisan
+
+ The actual job runners, these run in the background and consume whatever job API has scheduled next. Artisan instructs ffmpeg to run, or packages a previously transcoded asset to an HLS playlist and syncs it all to S3.
+
+
+
+
+
+
Stitcher
+
+ Also referred to as a "playlist manipulator," Stitcher can create a session for each user and generate a custom HLS playlist tailored to their needs, including resolution filtering and the addition of bumpers or linear ads. The stitcher has its own API. A swagger page is exposed on the /swagger endpoint.
+
+
+
+
+
+
Player
+
+ The player facade simplifies HLS.js with an intuitive API for building the player. It offers player-friendly methods, supports plugins, and provides React hooks for efficient state management.
+
+
+
+
+