Skip to content

Commit

Permalink
refactor: Update Transcoding service doc (#16)
Browse files Browse the repository at this point in the history
- Organized content into tabs for improved readability.
- Introduced the "error_message" field in the response JSON for transcoding errors.
- Included the S3 bucket URL in the input and output url
Chiranjeevinarukula authored Nov 22, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent da41a07 commit fc09359
Showing 3 changed files with 82 additions and 33 deletions.
35 changes: 35 additions & 0 deletions docs/transcoding-service/get-transcoding-job-details.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
sidebar_position: 3
---
# Get Transcoding Job detail

To retrieve the details of a transcoding job, make a GET request to the following API endpoint:

```base
https://app.tpstreams.com/api/v1/<organization_id>/transcoding_jobs/<job_id>/
```

Replace <organization_id> with your organization's unique identifier and <job_id> with the specific job ID you want to retrieve details for.

#### Sample Response

```json
{
"id": "5KQfnXCg8Qh",
"resolutions": [
"240p",
"480p"
],
"video_duration": 120,
"status": "Completed",
"input_url": "https://example.com/input-video.mp4",
"output_path": "s3://example-bucket/path/?access_key=E8WPS6H1A4OYD3ZNVMR&secret_key=N1dYpS2cTk5AeH6jWf8TgBh9Ji0MkL1N2O3P",
"start_time": "2023-04-20T23:20:06.034924+12:00",
"end_time": "2023-04-20T23:40:06.034924+12:00",
"error_message": null,
}
```
:::important
In case of transcoding errors, details will be provided in the "error_message" field of the response.
:::

68 changes: 35 additions & 33 deletions docs/transcoding-service/transcode-a-video.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,7 @@
---
sidebar_position: 1
sidebar_position: 2
---

# Introduction

Welcome to the Transcoding as a Service documentation! This guide will help you understand how to use our transcoding service to convert videos into different resolutions. Transcoding is the process of converting video files from one format to another or to different resolutions to make them compatible with various devices and streaming platforms.


### Trancode a video
# Trancode a video

To transcode a video, you need to make a POST request to the following API endpoint:

@@ -17,21 +11,34 @@ https://app.tpstreams.com/api/v1/<organization_id>/transcoding_jobs/
Replace <organization_id> with your organization's unique identifier.

#### Sample payload:
You have the flexibility to choose the method that best fits your workflow. Whether you prefer using an external video URL or a direct S3 bucket path, both options are available to you:

**1. External Video URL:**
```json
{
"input_url": "https://example.com/input-video.mp4",
"output_path": "s3://example-bucket/path/?access_key=<access_key>&secret_key=<secret_key>",
"output_path": "s3://example-bucket/path/?access_key=<access_key>&secret_key=<secret_key>&region=<region>",
"resolutions": ["240p", "480p"]
}
```

**2. Direct S3 Bucket Path:**

```json
{
"input_path": "s3://example-bucket/video.mp4/?access_key=<access_key>&secret_key=<secret_key>&region=<region>",
"output_path": "s3://example-bucket/path/?access_key=<access_key>&secret_key=<secret_key>&region=<region>",
"resolutions": ["240p", "480p"]
}
```

Here's a breakdown of the fields in the payload:

| Name | Description |
| --------------- | -------------------------------------------------------- |
| input_url | The URL of the input video file you want to transcode |
| output_path | The S3 bucket path where the transcoded video files will be stored. Make sure to specify a unique path for each transcoding job.The access_key and secret_key query parameters should have the same values as the access_key and secret key of the bucket.|
| resolutions | An array of resolutions you want to transcode the video into. You can specify multiple resolutions as needed. Available resoltions are 240p, 360p, 480p, 720p and 1080p |
| **Name** | **Description** |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| input_url | The URL of the input video file you want to transcode. **OR** The S3 bucket path of the input video file. If using the S3 path, ensure the access_key , secret_key and region match the bucket's credentials. |
| output_path | The S3 bucket path where the transcoded video files will be stored. Ensure a unique path for each transcoding job. The access_key , secret_key and region query parameters should match the bucket's credentials. |
| resolutions | An array of resolutions for transcoding the video. Specify multiple resolutions as needed. Options include 240p, 360p, 480p, 720p, and 1080p. |


#### Response
@@ -48,28 +55,23 @@ Upon a successful request, you will receive a response like below with informati
"video_duration": null,
"status": "Queued",
"input_url": "https://example.com/input-video.mp4",
"output_path": "s3://example-bucket/path/?access_key=E8WPS6H1A4OYD3ZNVMR&secret_key=N1dYpS2cTk5AeH6jWf8TgBh9Ji0MkL1N2O3P",
"output_path": "s3://example-bucket/path/?access_key=<access_key>&secret_key=<secret_key>&region=<region>",
"start_time": null,
"end_time": null
"end_time": null,
"error_message" : null,
}
```
:::important
In case of transcoding errors, details will be provided in the "error_message" field of the response.
:::


### Get notified on status change
We offer webhook integration to keep you informed about the status and progress of your transcoding jobs in real-time. With webhook integration, you can receive notifications as soon as your job status changes, making it easier to track and manage your video transcoding tasks.

To register a webhook for your organization, Please check webhook [documentation](../server-api/webhooks.md).

### Get Transcoding Job detail

To retrieve the details of a transcoding job, make a GET request to the following API endpoint:

```base
https://app.tpstreams.com/api/v1/<organization_id>/transcoding_jobs/<job_id>/
```

Replace <organization_id> with your organization's unique identifier and <job_id> with the specific job ID you want to retrieve details for.

#### Sample Response
Upon registering a webhook, you will receive a status change along with information about your transcoding job. Here is an example of the response you might receive:

```json
{
@@ -78,11 +80,11 @@ Replace <organization_id> with your organization's unique identifier and <job_id
"240p",
"480p"
],
"video_duration": 120,
"status": "Completed",
"video_duration": null,
"status": "transcoding",
"input_url": "https://example.com/input-video.mp4",
"output_path": "s3://example-bucket/path/?access_key=E8WPS6H1A4OYD3ZNVMR&secret_key=N1dYpS2cTk5AeH6jWf8TgBh9Ji0MkL1N2O3P",
"start_time": "2023-04-20T23:20:06.034924+12:00",
"end_time": "2023-04-20T23:40:06.034924+12:00"
"output_path": "s3://example-bucket/path/?access_key=<access_key>&secret_key=<secret_key>&region=<region>",
"start_time": "2023-11-22T12:30:00Z",
"end_time": null,
"error_message": null
}
```
12 changes: 12 additions & 0 deletions docs/transcoding-service/transcoding-service-introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
sidebar_position: 1
---
# Introduction

Welcome to the Transcoding as a Service documentation! This guide is your gateway to mastering our transcoding service, simplifying the process of converting videos into different resolutions. Transcoding is the key to ensuring your videos play smoothly on various devices and streaming platforms.



Refer the documentation below for more information.
- [Transcode a Video](transcode-a-video)
- [Get Transcoding Job Details](get-transcoding-job-details)

0 comments on commit fc09359

Please sign in to comment.