Skip to content

Commit 03448a4

Browse files
Stephen G. PopeStephen G. Pope
Stephen G. Pope
authored and
Stephen G. Pope
committed
added docs and updated
1 parent bcadff6 commit 03448a4

6 files changed

Lines changed: 609 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ Each endpoint is supported by robust payload validation and detailed API documen
8787
- Transcribes or translates audio/video content from a provided media URL.
8888
- [Documentation](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/media/media_transcribe.md)
8989

90+
- **`/v1/media/silence`**
91+
- Detects silence intervals in a given media file.
92+
- [Documentation](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/media/silence.md)
93+
9094
### S3
9195

9296
- **`/v1/s3/upload`**
@@ -117,6 +121,18 @@ Each endpoint is supported by robust payload validation and detailed API documen
117121
- Extracts a thumbnail image from a specific timestamp in a video.
118122
- [Documentation](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/video/thumbnail.md)
119123

124+
- **`/v1/video/cut`**
125+
- Cuts specified segments from a video file with optional encoding settings.
126+
- [Documentation](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/video/cut.md)
127+
128+
- **`/v1/video/split`**
129+
- Splits a video into multiple segments based on specified start and end times.
130+
- [Documentation](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/video/split.md)
131+
132+
- **`/v1/video/trim`**
133+
- Trims a video by keeping only the content between specified start and end times.
134+
- [Documentation](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/video/trim.md)
135+
120136
---
121137

122138
## Docker Build and Run

‎app.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,7 @@ def wrapper(*args, **kwargs):
170170
from routes.v1.media.silence import v1_media_silence_bp
171171
from routes.v1.video.cut import v1_video_cut_bp
172172
from routes.v1.video.split import v1_video_split_bp
173+
from routes.v1.video.trim import v1_video_trim_bp
173174

174175
app.register_blueprint(v1_ffmpeg_compose_bp)
175176
app.register_blueprint(v1_media_transcribe_bp)
@@ -194,6 +195,7 @@ def wrapper(*args, **kwargs):
194195
app.register_blueprint(v1_media_silence_bp)
195196
app.register_blueprint(v1_video_cut_bp)
196197
app.register_blueprint(v1_video_split_bp)
198+
app.register_blueprint(v1_video_trim_bp)
197199

198200
return app
199201

‎docs/video/split.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Video Split Endpoint
2+
3+
## 1. Overview
4+
5+
The `/v1/video/split` endpoint is part of the Video API and is used to split a video file into multiple segments based on specified start and end times. This endpoint fits into the overall API structure as a part of the version 1 (`v1`) routes, specifically under the `video` category.
6+
7+
## 2. Endpoint
8+
9+
**URL Path:** `/v1/video/split`
10+
**HTTP Method:** `POST`
11+
12+
## 3. Request
13+
14+
### Headers
15+
16+
- `x-api-key` (required): The API key for authentication.
17+
18+
### Body Parameters
19+
20+
The request body must be a JSON object with the following properties:
21+
22+
- `video_url` (required, string): The URL of the video file to be split.
23+
- `splits` (required, array of objects): An array of objects specifying the start and end times for each split. Each object must have the following properties:
24+
- `start` (required, string): The start time of the split in the format `hh:mm:ss.ms`.
25+
- `end` (required, string): The end time of the split in the format `hh:mm:ss.ms`.
26+
- `video_codec` (optional, string): The video codec to use for encoding the split videos. Default is `libx264`.
27+
- `video_preset` (optional, string): The video preset to use for encoding the split videos. Default is `medium`.
28+
- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding. Must be between 0 and 51. Default is 23.
29+
- `audio_codec` (optional, string): The audio codec to use for encoding the split videos. Default is `aac`.
30+
- `audio_bitrate` (optional, string): The audio bitrate to use for encoding the split videos. Default is `128k`.
31+
- `webhook_url` (optional, string): The URL to receive a webhook notification when the split operation is complete.
32+
- `id` (optional, string): A unique identifier for the request.
33+
34+
### Example Request
35+
36+
```json
37+
{
38+
"video_url": "https://example.com/video.mp4",
39+
"splits": [
40+
{
41+
"start": "00:00:10.000",
42+
"end": "00:00:20.000"
43+
},
44+
{
45+
"start": "00:00:30.000",
46+
"end": "00:00:40.000"
47+
}
48+
],
49+
"video_codec": "libx264",
50+
"video_preset": "medium",
51+
"video_crf": 23,
52+
"audio_codec": "aac",
53+
"audio_bitrate": "128k",
54+
"webhook_url": "https://example.com/webhook",
55+
"id": "unique-request-id"
56+
}
57+
```
58+
59+
```bash
60+
curl -X POST \
61+
https://api.example.com/v1/video/split \
62+
-H 'x-api-key: YOUR_API_KEY' \
63+
-H 'Content-Type: application/json' \
64+
-d '{
65+
"video_url": "https://example.com/video.mp4",
66+
"splits": [
67+
{
68+
"start": "00:00:10.000",
69+
"end": "00:00:20.000"
70+
},
71+
{
72+
"start": "00:00:30.000",
73+
"end": "00:00:40.000"
74+
}
75+
],
76+
"video_codec": "libx264",
77+
"video_preset": "medium",
78+
"video_crf": 23,
79+
"audio_codec": "aac",
80+
"audio_bitrate": "128k",
81+
"webhook_url": "https://example.com/webhook",
82+
"id": "unique-request-id"
83+
}'
84+
```
85+
86+
## 4. Response
87+
88+
### Success Response
89+
90+
The success response follows the general response format specified in `app.py`. Here's an example:
91+
92+
```json
93+
{
94+
"endpoint": "/v1/video/split",
95+
"code": 200,
96+
"id": "unique-request-id",
97+
"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
98+
"response": [
99+
{
100+
"file_url": "https://example.com/split-1.mp4"
101+
},
102+
{
103+
"file_url": "https://example.com/split-2.mp4"
104+
}
105+
],
106+
"message": "success",
107+
"pid": 12345,
108+
"queue_id": 6789,
109+
"run_time": 5.234,
110+
"queue_time": 0.123,
111+
"total_time": 5.357,
112+
"queue_length": 0,
113+
"build_number": "1.0.0"
114+
}
115+
```
116+
117+
The `response` field contains an array of objects, each representing a split video file. Each object has a `file_url` property containing the URL of the split video file.
118+
119+
### Error Responses
120+
121+
- **400 Bad Request**: Returned when the request payload is missing or invalid.
122+
- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
123+
- **429 Too Many Requests**: Returned when the maximum queue length has been reached.
124+
- **500 Internal Server Error**: Returned when an unexpected error occurs during the video split process.
125+
126+
Example error response:
127+
128+
```json
129+
{
130+
"code": 400,
131+
"id": "unique-request-id",
132+
"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
133+
"message": "Invalid request payload: 'splits' is a required property",
134+
"pid": 12345,
135+
"queue_id": 6789,
136+
"queue_length": 2,
137+
"build_number": "1.0.0"
138+
}
139+
```
140+
141+
## 5. Error Handling
142+
143+
The endpoint handles the following common errors:
144+
145+
- Missing or invalid request parameters: Returns a 400 Bad Request error with a descriptive error message.
146+
- Authentication failure: Returns a 401 Unauthorized error if the `x-api-key` header is missing or invalid.
147+
- Queue length exceeded: Returns a 429 Too Many Requests error if the maximum queue length has been reached.
148+
- Unexpected exceptions: Returns a 500 Internal Server Error with the exception message.
149+
150+
The main application context (`app.py`) also includes error handling for queue length limits and webhook notifications.
151+
152+
## 6. Usage Notes
153+
154+
- The `video_url` parameter must be a valid URL pointing to a video file.
155+
- The `splits` array must contain at least one object specifying the start and end times for a split.
156+
- The start and end times must be in the format `hh:mm:ss.ms` (hours:minutes:seconds.milliseconds).
157+
- The `video_codec`, `video_preset`, `video_crf`, `audio_codec`, and `audio_bitrate` parameters are optional and can be used to customize the encoding settings for the split videos.
158+
- If the `webhook_url` parameter is provided, a webhook notification will be sent to the specified URL when the split operation is complete.
159+
- The `id` parameter is optional and can be used to uniquely identify the request.
160+
161+
## 7. Common Issues
162+
163+
- Providing an invalid or inaccessible `video_url`.
164+
- Specifying overlapping or invalid start and end times in the `splits` array.
165+
- Exceeding the maximum queue length, which can result in a 429 Too Many Requests error.
166+
167+
## 8. Best Practices
168+
169+
- Validate the `video_url` parameter before sending the request to ensure it points to a valid video file.
170+
- Ensure that the start and end times in the `splits` array are correctly formatted and do not overlap.
171+
- Consider using the `webhook_url` parameter to receive notifications about the completion of the split operation, especially for long-running or asynchronous requests.
172+
- Implement retry mechanisms and error handling in your client application to handle potential errors and failures.
173+
- Monitor the queue length and adjust the `MAX_QUEUE_LENGTH` environment variable as needed to prevent excessive queuing and potential timeouts.

‎docs/video/trim.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Video Trim Endpoint
2+
3+
## 1. Overview
4+
5+
The `/v1/video/trim` endpoint is part of the Video API and allows users to trim a video by removing specified portions from the beginning and/or end. It also provides optional encoding settings to control the output video quality. This endpoint fits into the overall API structure as a part of the version 1 (`v1`) routes, specifically under the `video` category.
6+
7+
## 2. Endpoint
8+
9+
**URL Path:** `/v1/video/trim`
10+
**HTTP Method:** `POST`
11+
12+
## 3. Request
13+
14+
### Headers
15+
16+
- `x-api-key` (required): The API key for authentication.
17+
18+
### Body Parameters
19+
20+
- `video_url` (required, string): The URL of the video file to be trimmed.
21+
- `start` (optional, string): The start time for trimming in the format `hh:mm:ss` or `mm:ss`.
22+
- `end` (optional, string): The end time for trimming in the format `hh:mm:ss` or `mm:ss`.
23+
- `video_codec` (optional, string): The video codec to be used for encoding the output video. Default is `libx264`.
24+
- `video_preset` (optional, string): The video preset to be used for encoding the output video. Default is `medium`.
25+
- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding, ranging from 0 to 51. Default is 23.
26+
- `audio_codec` (optional, string): The audio codec to be used for encoding the output video. Default is `aac`.
27+
- `audio_bitrate` (optional, string): The audio bitrate to be used for encoding the output video. Default is `128k`.
28+
- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion of the task.
29+
- `id` (optional, string): A unique identifier for the request.
30+
31+
The `validate_payload` directive in the routes file ensures that the request payload adheres to the specified schema, which includes the required and optional parameters, their data types, and any additional constraints.
32+
33+
### Example Request
34+
35+
```json
36+
{
37+
"video_url": "https://example.com/video.mp4",
38+
"start": "00:01:00",
39+
"end": "00:03:00",
40+
"video_codec": "libx264",
41+
"video_preset": "faster",
42+
"video_crf": 28,
43+
"audio_codec": "aac",
44+
"audio_bitrate": "128k",
45+
"webhook_url": "https://example.com/webhook",
46+
"id": "unique-request-id"
47+
}
48+
```
49+
50+
```bash
51+
curl -X POST \
52+
https://api.example.com/v1/video/trim \
53+
-H 'x-api-key: YOUR_API_KEY' \
54+
-H 'Content-Type: application/json' \
55+
-d '{
56+
"video_url": "https://example.com/video.mp4",
57+
"start": "00:01:00",
58+
"end": "00:03:00",
59+
"video_codec": "libx264",
60+
"video_preset": "faster",
61+
"video_crf": 28,
62+
"audio_codec": "aac",
63+
"audio_bitrate": "128k",
64+
"webhook_url": "https://example.com/webhook",
65+
"id": "unique-request-id"
66+
}'
67+
```
68+
69+
## 4. Response
70+
71+
### Success Response
72+
73+
The success response follows the general response structure defined in the `app.py` file. Here's an example:
74+
75+
```json
76+
{
77+
"endpoint": "/v1/video/trim",
78+
"code": 200,
79+
"id": "unique-request-id",
80+
"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
81+
"response": "https://example.com/trimmed-video.mp4",
82+
"message": "success",
83+
"pid": 12345,
84+
"queue_id": 6789,
85+
"run_time": 5.234,
86+
"queue_time": 0.123,
87+
"total_time": 5.357,
88+
"queue_length": 0,
89+
"build_number": "1.0.0"
90+
}
91+
```
92+
93+
### Error Responses
94+
95+
- **400 Bad Request**: Returned when the request payload is missing or contains invalid parameters.
96+
97+
```json
98+
{
99+
"code": 400,
100+
"message": "Invalid request payload"
101+
}
102+
```
103+
104+
- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
105+
106+
```json
107+
{
108+
"code": 401,
109+
"message": "Unauthorized"
110+
}
111+
```
112+
113+
- **500 Internal Server Error**: Returned when an unexpected error occurs during the video trimming process.
114+
115+
```json
116+
{
117+
"code": 500,
118+
"message": "An error occurred during the video trimming process"
119+
}
120+
```
121+
122+
## 5. Error Handling
123+
124+
The endpoint handles common errors such as missing or invalid parameters by returning appropriate HTTP status codes and error messages. The `validate_payload` decorator ensures that the request payload adheres to the specified schema, and any violations will result in a 400 Bad Request error.
125+
126+
The main application context (`app.py`) includes error handling for the task queue. If the maximum queue length is reached, the endpoint will return a 429 Too Many Requests error with a corresponding message.
127+
128+
## 6. Usage Notes
129+
130+
- The `start` and `end` parameters are optional, but at least one of them must be provided to perform the trimming operation.
131+
- The `video_codec`, `video_preset`, `video_crf`, `audio_codec`, and `audio_bitrate` parameters are optional and allow users to customize the encoding settings for the output video.
132+
- The `webhook_url` parameter is optional and can be used to receive a notification when the task is completed.
133+
- The `id` parameter is optional and can be used to uniquely identify the request.
134+
135+
## 7. Common Issues
136+
137+
- Providing an invalid or inaccessible `video_url`.
138+
- Specifying invalid or unsupported values for the encoding parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`).
139+
- Encountering issues with the video trimming process due to unsupported video formats or corrupted files.
140+
141+
## 8. Best Practices
142+
143+
- Validate the `video_url` parameter to ensure it points to a valid and accessible video file.
144+
- Use appropriate encoding settings based on the desired output quality and file size requirements.
145+
- Implement error handling and retry mechanisms for failed requests or network issues.
146+
- Monitor the task queue length and adjust the `MAX_QUEUE_LENGTH` value accordingly to prevent overloading the system.
147+
- Implement rate limiting or throttling mechanisms to prevent abuse or excessive requests.

0 commit comments

Comments
 (0)