chore: Code structure for docs and artisan

.github/workflows/deploy-docs.yml

@@ -46,7 +46,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: packages/docs/.vitepress/dist
+          path: docs/.vitepress/dist
 
   # Deployment job
   deploy:

packages/docs/.vitepress/config.mts → docs/.vitepress/config.mts

@@ -26,10 +26,31 @@ export default defineConfig({
       {
         text: "Features",
         items: [
-          { text: "Transcode", link: "features/transcode" },
-          { text: "Package", link: "features/package" },
-          { text: "Stitcher", link: "features/stitcher" },
-          { text: "Dashboard", link: "features/dashboard" },
+          {
+            text: '<div class="navitem-img"><img src="/mixwave/transcode.svg" /> Transcode</div>',
+            link: "features/transcode",
+          },
+          {
+            text: '<div class="navitem-img"><img src="/mixwave/package.svg" /> Package</div>',
+            link: "features/package",
+          },
+          {
+            text: '<div class="navitem-img"><img src="/mixwave/stitcher.svg" /> Stitcher</div>',
+            link: "features/stitcher",
+          },
+        ],
+      },
+      {
+        text: "Frontend",
+        items: [
+          {
+            text: '<div class="navitem-img"><img src="/mixwave/player.svg" /> Player</div>',
+            link: "frontend/player",
+          },
+          {
+            text: '<div class="navitem-img"><img src="/mixwave/dashboard.svg" /> Dashboard</div>',
+            link: "frontend/dashboard",
+          },
         ],
       },
       {

packages/docs/.vitepress/theme/custom.css → docs/.vitepress/theme/custom.css

@@ -32,3 +32,17 @@ summary {
   border: 1px solid #aaa;
   border-radius: 6px;
 }
+
+.navitem-img {
+  display: flex;
+}
+
+.navitem-img img {
+  width: 16px;
+  margin-right: 4px;
+}
+
+.video-frame {
+  border-radius: 12px;
+  overflow: hidden;
+}

docs/features/package.md

@@ -0,0 +1,59 @@
+---
+next:
+  text: "Features: Stitcher"
+  link: "/features/stitcher"
+---
+
+# Package
+
+Video packaging refers to the process of preparing a video file for delivery and consumption by users across different devices and platforms.
+
+- The video is split into smaller segments or chunks, usually a few seconds long, to facilitate adaptive bitrate streaming (ABR), which adjusts quality based on network conditions.
+
+- A manifest file (m3u8 for HLS) is generated. It contains metadata about the available segments, bitrates, and resolutions, helping the player know what content to request based on the user’s network conditions.
+
+## API
+
+The package job will prepare an HLS playlist for your asset. Before you package, check the [transcode](/features/transcode) instructions.
+
+::: code-group
+
+```sh [shell]
+curl -X POST https://api.domain.com/package
+  -H "Content-Type: application/json"
+  -d "{body}"
+```
+
+:::
+
+A minimal body payload may look like this:
+
+```json
+{
+  "assetId": "f7e89553-0d3b-4982-ba7b-3ce5499ac689"
+}
+```
+
+Your asset is now available for playback at:
+
+```
+{S3_PUBLIC_URL}/package/f7e89553-0d3b-4982-ba7b-3ce5499ac689/hls/master.m3u8
+```
+
+::: tip
+Each package result is uploaded to /package/{assetId}/hls/master.m3u8
+:::
+
+## Example
+
+We started by [transcoding](/features/transcode#example) two input files (content.mp4 and bumper.mp4) to multiple streams. We'll now package these their HLS master and media playlists files.
+
+```
+input   = 67b070fd-5db6-4022-a568-652abdbfac9c
+output  = https://my.cdn/package/67b070fd-5db6-4022-a568-652abdbfac9c/hls/master.m3u8
+```
+
+```
+input   = 13b1d432-ec8e-4516-9904-df1aa90db803
+output  = https://my.cdn/package/13b1d432-ec8e-4516-9904-df1aa90db803/hls/master.m3u8
+```

packages/docs/features/stitcher.md → docs/features/stitcher.md

@@ -1,7 +1,7 @@
 ---
 next:
-  text: "Features: Dashboard"
-  link: "/features/dashboard"
+  text: "Frontend: Player"
+  link: "/frontend/player"
 ---
 
 # Stitcher
@@ -68,6 +68,8 @@ Let's say you transcoded and packaged a new asset with the id `abbda878-8e08-40f
 }
 ```
 
+<video class="video-frame" src="/dashboard-player-bumper.mp4" controls></video>
+
 ### VMAP
 
 Instruct stitcher to add interstitials based on VMAP definitions. Each VMAP contains one or more `AdBreak` elements with a position of where the interstitial should be.
@@ -89,3 +91,21 @@ Instruct stitcher to add interstitials based on VMAP definitions. Each VMAP cont
 ::: warning
 Ad impressions are not tracked yet, we'd eventually like to provide a client wrapper that tracks ads in a certified manner.
 :::
+
+<video class="video-frame" src="/dashboard-player-vmap.mp4" controls></video>
+
+## Example
+
+In the [package](/features/package#example) and [transcode](/features/transcode#example) example we created 2 HLS master playlists, we can create a new master playlist on the fly which mimics the content asset id (originally from content.mp4), and add a bumper interstitial at time 0.
+
+```
+input   = - assetId: 67b070fd-5db6-4022-a568-652abdbfac9c
+          - interstitials: [
+              {
+                timeOffset: 0,
+                assetId: 13b1d432-ec8e-4516-9904-df1aa90db803
+              }
+            ]
+
+output  = http://my.stitcher/session/7b2a354a-69e3-4c16-accb-aa521c8b9d5b/master.m3u8
+```

packages/docs/features/transcode.md → docs/features/transcode.md

@@ -6,6 +6,22 @@ next:
 
 # Transcode
 
+Video transcoding is the process of converting video 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. Why is it important, you may ask?
+
+- Different devices and internet connections handle video data differently. High-quality video can consume a lot of bandwidth, which might not be available to all users, especially those with slower internet speeds. By transcoding videos into lower-resolution formats, the video becomes more accessible without consuming too much bandwidth.
+
+- Platforms like YouTube and Netflix use adaptive streaming to deliver videos. They transcode videos into multiple resolutions (e.g., 1080p, 720p, 480p). When you watch a video, the platform automatically adjusts the video quality based on your internet speed. If your connection is fast, you get high-quality video; if it's slow, you get a lower-quality version to prevent buffering.
+
+This dynamic delivery ensures smooth playback across various network conditions and devices, making the video experience better for everyone.
+
+## Dashboard
+
+You can use the dashboard to either view pending, processing, finished or failed transcode jobs, or you can use it to interact with the API. In the video below, we'll demonstrate how to transcode an mp4 file to a variety of streams.
+
+<video class="video-frame" src="/dashboard-transcode.mp4" controls></video>
+
+## API
+
 The transcode endpoint will push a job to the queue. The trancode job will create a separate ffmpeg job for each output stream defined in the body.
 
 ::: code-group
@@ -93,4 +109,27 @@ At this point, our asset (a collection of streams) is ready for packaging, and c
 Know that the result of a transcode job is merely an intermediary format. Typically, you'd transcode your input once and package as many times as you like for specific devices or use cases.
 :::
 
-Mixwave' transcode API works slightly different than what others do. We emphasize the idea to define what you have (input) and what you need (streams), and the system shall figure out how to craft the streams. There's no need to directly link a stream with a given output.
+Mixwave' transcode API works slightly different than what others do. We emphasize the idea to define what you have (input) and what you need (streams), and the system shall figure out how to craft the streams. There's no need to directly link an input with a given output.
+
+## Example
+
+In the example below, we'll transcode 2 mp4 files (content.mp4 and bumper.mp4) to 2 video tracks and an English audio track. The result are 2 asset id's, one for each.
+
+```
+input   = content.mp4
+
+streams = - video 1080p
+          - video 720p
+          - audio eng
+
+output  = 67b070fd-5db6-4022-a568-652abdbfac9c
+```
+
+```
+input   = bumper.mp4
+
+streams = - video 720p
+          - audio eng
+
+output  = 13b1d432-ec8e-4516-9904-df1aa90db803
+```

packages/docs/features/dashboard.md → docs/frontend/dashboard.md

@@ -1,13 +1,15 @@
+---
+next: false
+---
+
 # Dashboard
 
 The dashboard is a client application that visualizes running jobs, its statuses and has auto-generated API documentation based on the `spec.json` API endpoint. The API documentation is built with [Scalar](https://github.com/scalar/scalar). It's a React app and does not require separate a backend to function.
 
 Typically, you'd want to build the dashboard once and upload it to `S3` to serve it as a static site. The dashboard is an SPA and requires no separate server / backend to function.
 
-You can use the API docs to `Test Request`.
-
-<img class="image" src="../assets/dashboard-api.png" alt="Dashboard API" />
+<video class="video-frame" src="/dashboard-jobs.mp4" controls></video>
 
-Each job, or child job, has detailed logs.
+You can use the API docs to interact with the API, as seen here:
 
-<img class="image" src="../assets/dashboard-job.png" alt="Dashboard job" />
+<video class="video-frame" src="/dashboard-transcode.mp4" controls></video>

docs/frontend/player.md

@@ -0,0 +1,11 @@
+---
+next:
+  text: "Frontend: Dashboard"
+  link: "/frontend/dashboard"
+---
+
+# Player
+
+Coming soon!
+
+Meanwhile, we've got a couple of player video's on the [stitcher](/features/stitcher) page.

packages/docs/index.md → docs/index.md

@@ -23,11 +23,15 @@ features:
     icon:
       src: /transcode.svg
   - title: Package
-    details: Prepare and organize video files for delivery and playback.
+    details: Prepare and organize video files for delivery and playback. Upload directly to S3.
     icon:
       src: /package.svg
-  - title: Stitch
+  - title: Stitcher
     details: Manipulate and craft HLS playlists on the fly, supports HLS interstitials.
     icon:
-      src: /stitch.svg
+      src: /stitcher.svg
+  - title: Player
+    details: A unified <a href="https://github.com/video-dev/hls.js">hls.js</a> API and React components that integrate seamlessly.
+    icon:
+      src: /player.svg
 ---

packages/docs/introduction.md → docs/introduction.md

@@ -33,27 +33,6 @@ The process of converting a video file from one format or codec to another. The
 Consider the result of a transcode job as an intermediate format ready for packaging.
 :::
 
-<details>
-<summary>Mock example</summary>
-
-```
-input   = content.mp4
-streams = - video 1080p
-          - video 720p
-          - audio eng
-output  = 67b070fd-5db6-4022-a568-652abdbfac9c
-```
-
-```
-input   = bumper.mp4
-streams = - video 1080p
-          - video 720p
-          - audio eng
-output  = 13b1d432-ec8e-4516-9904-df1aa90db803
-```
-
-</details>
-
 ### <img src="/package.svg" class="title-image" /> Package
 
 The process of preparing and organizing video files for delivery and playback over various streaming platforms and devices. Packaging isn't as resource intensive as transcoding. The [package](/features/package) job generates an HLS playlist from the output of a transcode job. Basically, it comes down to the following steps:
@@ -73,22 +52,7 @@ As with transcode, the end result will be uploaded to your configured `S3` bucke
 At this point, your stream can be played by HLS-compatible players, such as [HLS.js](https://github.com/video-dev/hls.js), or natively on Apple devices.
 :::
 
-<details>
-<summary>Mock example</summary>
-
-```
-input   = 67b070fd-5db6-4022-a568-652abdbfac9c
-output  = https://my.cdn/package/67b070fd-5db6-4022-a568-652abdbfac9c/hls/master.m3u8
-```
-
-```
-input   = 13b1d432-ec8e-4516-9904-df1aa90db803
-output  = https://my.cdn/package/13b1d432-ec8e-4516-9904-df1aa90db803/hls/master.m3u8
-```
-
-</details>
-
-### <img src="/stitch.svg" class="title-image" /> Stitch
+### <img src="/stitcher.svg" class="title-image" /> Stitch
 
 At this point, you've created playable assets. Stitching involves serving the manifest through a proxy that can modify the output based on different parameters. If you're looking to dynamically merge manifests, stitch them together, or add interstitials, this is for you.
 
@@ -98,17 +62,6 @@ At this point, you've created playable assets. Stitching involves serving the ma
 The stitch API is quite limited at the moment, but let us know what features you'd like by submitting a [feature ticket](https://github.com/matvp91/mixwave/issues).
 :::
 
-<details>
-<summary>Mock example</summary>
-
-```
-input   = - assetId: 67b070fd-5db6-4022-a568-652abdbfac9c
-          - bumperAssetId: 13b1d432-ec8e-4516-9904-df1aa90db803
-output  = http://stitcher.mixwave/session/7b2a354a-69e3-4c16-accb-aa521c8b9d5b/master.m3u8
-```
-
-</details>
-
 ## Structure
 
 Mixwave consists of the following packages: