Skip to content

Commit a41b931

Browse files
Stephen G. PopeStephen G. Pope
Stephen G. Pope
authored and
Stephen G. Pope
committed
added new endpoints and docs
1 parent 9b581bf commit a41b931

5 files changed

Lines changed: 651 additions & 117 deletions

File tree

‎docs/media/cut.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Media Cut Endpoint
2+
3+
## 1. Overview
4+
5+
The `/v1/media/cut` endpoint is part of the Flask API application and is designed to cut specified segments from a media file (video or audio) with optional encoding settings. This endpoint fits into the overall API structure as a part of the `v1` blueprint, which contains various media-related functionalities.
6+
7+
## 2. Endpoint
8+
9+
**URL Path:** `/v1/media/cut`
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+
- `media_url` (required, string): The URL of the media file to be cut.
23+
- `cuts` (required, array of objects): An array of cut segments, where each object has the following properties:
24+
- `start` (required, string): The start time of the cut segment in the format `hh:mm:ss.ms`.
25+
- `end` (required, string): The end time of the cut segment in the format `hh:mm:ss.ms`.
26+
- `video_codec` (optional, string): The video codec to be used for encoding the output file. Default is `libx264`.
27+
- `video_preset` (optional, string): The video preset to be used for encoding the output file. 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 be used for encoding the output file. Default is `aac`.
30+
- `audio_bitrate` (optional, string): The audio bitrate to be used for encoding the output file. Default is `128k`.
31+
- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion of the task.
32+
- `id` (optional, string): A unique identifier for the request.
33+
34+
### Example Request
35+
36+
```json
37+
{
38+
"media_url": "https://example.com/video.mp4",
39+
"cuts": [
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+
```
60+
curl -X POST \
61+
https://api.example.com/v1/media/cut \
62+
-H 'x-api-key: YOUR_API_KEY' \
63+
-H 'Content-Type: application/json' \
64+
-d '{
65+
"media_url": "https://example.com/video.mp4",
66+
"cuts": [
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 structure defined in the `app.py` file. Here's an example:
91+
92+
```json
93+
{
94+
"code": 200,
95+
"id": "unique-request-id",
96+
"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
97+
"response": {
98+
"file_url": "https://example.com/output.mp4"
99+
},
100+
"message": "success",
101+
"run_time": 5.234,
102+
"queue_time": 0.012,
103+
"total_time": 5.246,
104+
"pid": 12345,
105+
"queue_id": 1234567890,
106+
"queue_length": 0,
107+
"build_number": "1.0.0"
108+
}
109+
```
110+
111+
### Error Responses
112+
113+
- **400 Bad Request**: Returned when the request payload is missing or invalid.
114+
115+
```json
116+
{
117+
"code": 400,
118+
"message": "Invalid request payload"
119+
}
120+
```
121+
122+
- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
123+
124+
```json
125+
{
126+
"code": 401,
127+
"message": "Unauthorized"
128+
}
129+
```
130+
131+
- **500 Internal Server Error**: Returned when an unexpected error occurs on the server.
132+
133+
```json
134+
{
135+
"code": 500,
136+
"message": "Internal Server Error"
137+
}
138+
```
139+
140+
## 5. Error Handling
141+
142+
The endpoint handles the following common errors:
143+
144+
- Missing or invalid request parameters: Returns a 400 Bad Request error.
145+
- Authentication failure: Returns a 401 Unauthorized error if the `x-api-key` header is missing or invalid.
146+
- Unexpected exceptions: Returns a 500 Internal Server Error if an unexpected exception occurs during the media cut process.
147+
148+
The main application context (`app.py`) also includes error handling for queue overload. If the maximum queue length is reached, the endpoint returns a 429 Too Many Requests error.
149+
150+
## 6. Usage Notes
151+
152+
- The `media_url` parameter must be a valid URL pointing to a media file (video or audio).
153+
- The `cuts` parameter must be an array of objects, where each object specifies a start and end time for a cut segment in the format `hh:mm:ss.ms`.
154+
- The optional encoding parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`) can be used to customize the output file encoding settings.
155+
- The `webhook_url` parameter is optional and can be used to receive a webhook notification upon completion of the task.
156+
- The `id` parameter is optional and can be used to uniquely identify the request.
157+
158+
## 7. Common Issues
159+
160+
- Providing an invalid or inaccessible `media_url`.
161+
- Providing invalid or out-of-range values for the encoding parameters.
162+
- Providing overlapping or invalid cut segments in the `cuts` parameter.
163+
164+
## 8. Best Practices
165+
166+
- Validate the input parameters on the client-side before sending the request.
167+
- Use the `webhook_url` parameter to receive notifications and handle the response asynchronously.
168+
- Monitor the `queue_length` parameter in the response to manage the load on the API.
169+
- Use the `id` parameter to correlate requests and responses for better tracking and debugging.

‎docs/media/silence.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Silence Detection Endpoint
2+
3+
## 1. Overview
4+
5+
The `/v1/media/silence` endpoint is part of the Media API and is designed to detect silence intervals in a given media file. It takes a media URL, along with various parameters for configuring the silence detection process, and returns the detected silence intervals. This endpoint fits into the overall API structure as a part of the version 1 (v1) media-related endpoints.
6+
7+
## 2. Endpoint
8+
9+
```
10+
POST /v1/media/silence
11+
```
12+
13+
## 3. Request
14+
15+
### Headers
16+
17+
- `x-api-key` (required): The API key for authentication.
18+
19+
### Body Parameters
20+
21+
The request body should be a JSON object with the following parameters:
22+
23+
- `media_url` (required, string): The URL of the media file to be processed.
24+
- `start` (optional, string): The start time for the silence detection process, in the format `HH:MM:SS.ms`. If not provided, the process will start from the beginning of the media file.
25+
- `end` (optional, string): The end time for the silence detection process, in the format `HH:MM:SS.ms`. If not provided, the process will continue until the end of the media file.
26+
- `noise` (optional, string): The noise threshold for silence detection, in decibels (dB). Default is `-30dB`.
27+
- `duration` (required, number): The minimum duration (in seconds) for a silence interval to be considered valid.
28+
- `mono` (optional, boolean): Whether to process the audio as mono (single channel) or not. Default is `true`.
29+
- `webhook_url` (required, string): The URL to which the response should be sent as a webhook.
30+
- `id` (required, string): A unique identifier for the request.
31+
32+
The `validate_payload` directive in the routes file enforces the following JSON schema for the request body:
33+
34+
```python
35+
{
36+
"type": "object",
37+
"properties": {
38+
"media_url": {"type": "string", "format": "uri"},
39+
"start": {"type": "string"},
40+
"end": {"type": "string"},
41+
"noise": {"type": "string"},
42+
"duration": {"type": "number", "minimum": 0.1},
43+
"mono": {"type": "boolean"},
44+
"webhook_url": {"type": "string", "format": "uri"},
45+
"id": {"type": "string"}
46+
},
47+
"required": ["media_url", "duration"],
48+
"additionalProperties": False
49+
}
50+
```
51+
52+
### Example Request
53+
54+
```json
55+
{
56+
"media_url": "https://example.com/audio.mp3",
57+
"start": "00:00:10.0",
58+
"end": "00:01:00.0",
59+
"noise": "-25dB",
60+
"duration": 0.5,
61+
"mono": false,
62+
"webhook_url": "https://example.com/webhook",
63+
"id": "unique-request-id"
64+
}
65+
```
66+
67+
```
68+
curl -X POST \
69+
https://api.example.com/v1/media/silence \
70+
-H 'x-api-key: YOUR_API_KEY' \
71+
-H 'Content-Type: application/json' \
72+
-d '{
73+
"media_url": "https://example.com/audio.mp3",
74+
"start": "00:00:10.0",
75+
"end": "00:01:00.0",
76+
"noise": "-25dB",
77+
"duration": 0.5,
78+
"mono": false,
79+
"webhook_url": "https://example.com/webhook",
80+
"id": "unique-request-id"
81+
}'
82+
```
83+
84+
## 4. Response
85+
86+
### Success Response
87+
88+
The success response will be sent as a webhook to the specified `webhook_url`. The response format follows the general response structure defined in the main application context (`app.py`). Here's an example:
89+
90+
```json
91+
{
92+
"endpoint": "/v1/media/silence",
93+
"code": 200,
94+
"id": "unique-request-id",
95+
"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
96+
"response": [
97+
{
98+
"start": 10.5,
99+
"end": 15.2
100+
},
101+
{
102+
"start": 20.0,
103+
"end": 25.7
104+
}
105+
],
106+
"message": "success",
107+
"pid": 12345,
108+
"queue_id": 1234567890,
109+
"run_time": 1.234,
110+
"queue_time": 0.123,
111+
"total_time": 1.357,
112+
"queue_length": 0,
113+
"build_number": "1.0.0"
114+
}
115+
```
116+
117+
### Error Responses
118+
119+
- **400 Bad Request**: This error is returned when the request body is missing or contains invalid parameters. Example response:
120+
121+
```json
122+
{
123+
"code": 400,
124+
"message": "Invalid request payload"
125+
}
126+
```
127+
128+
- **401 Unauthorized**: This error is returned when the `x-api-key` header is missing or invalid. Example response:
129+
130+
```json
131+
{
132+
"code": 401,
133+
"message": "Unauthorized"
134+
}
135+
```
136+
137+
- **500 Internal Server Error**: This error is returned when an unexpected error occurs during the silence detection process. Example response:
138+
139+
```json
140+
{
141+
"code": 500,
142+
"message": "An error occurred during the silence detection process"
143+
}
144+
```
145+
146+
## 5. Error Handling
147+
148+
The endpoint handles the following common errors:
149+
150+
- Missing or invalid request parameters: Returns a 400 Bad Request error.
151+
- Missing or invalid `x-api-key` header: Returns a 401 Unauthorized error.
152+
- Unexpected exceptions during the silence detection process: Returns a 500 Internal Server Error.
153+
154+
The main application context (`app.py`) also includes error handling for situations where the task queue has reached its maximum length (`MAX_QUEUE_LENGTH`). In such cases, a 429 Too Many Requests error is returned.
155+
156+
## 6. Usage Notes
157+
158+
- The `media_url` parameter should point to a valid media file that can be processed by the silence detection service.
159+
- The `start` and `end` parameters are optional and can be used to specify a time range within the media file for silence detection.
160+
- The `noise` parameter allows you to adjust the noise threshold for silence detection. Lower values (e.g., `-40dB`) will detect more silence intervals, while higher values (e.g., `-20dB`) will detect fewer silence intervals.
161+
- The `duration` parameter specifies the minimum duration (in seconds) for a silence interval to be considered valid. This can be useful for filtering out very short silence intervals that may not be relevant.
162+
- The `mono` parameter determines whether the audio should be processed as a single channel (mono) or multiple channels (stereo or surround).
163+
164+
## 7. Common Issues
165+
166+
- Providing an invalid or inaccessible `media_url`.
167+
- Specifying `start` and `end` times that are outside the duration of the media file.
168+
- Setting the `duration` parameter to an unreasonably low value, which may result in detecting too many short silence intervals.
169+
170+
## 8. Best Practices
171+
172+
- Validate the `media_url` parameter to ensure it points to a valid and accessible media file.
173+
- Consider using the `start` and `end` parameters to focus the silence detection on a specific time range within the media file, if needed.
174+
- Adjust the `noise` and `duration` parameters based on your specific use case and requirements for silence detection.
175+
- If you need to process stereo or surround audio, set the `mono` parameter to `false`.
176+
- Monitor the response from the endpoint to ensure that the silence detection process completed successfully and that the detected silence intervals meet your expectations.

0 commit comments

Comments
 (0)