fix to captions docs

Author: Stephen G. Pope

docs/video/caption_video.md

@@ -20,7 +20,11 @@ The `/v1/video/caption` endpoint is part of the Video API and is responsible for
 The request body must be a JSON object with the following properties:
 
 - `video_url` (string, required): The URL of the video file to be captioned.
-- `captions` (string, optional): The caption text to be added to the video.
+- `captions` (string, optional): Can be one of the following:
+  - Raw caption text to be added to the video
+  - URL to an SRT subtitle file
+  - URL to an ASS subtitle file
+  - If not provided, the system will automatically generate captions by transcribing the audio from the video
 - `settings` (object, optional): An object containing various styling options for the captions. See the schema below for available options.
 - `replace` (array, optional): An array of objects with `find` and `replace` properties, specifying text replacements to be made in the captions.
 - `webhook_url` (string, optional): A URL to receive a webhook notification when the captioning process is complete.
@@ -60,7 +64,13 @@ The request body must be a JSON object with the following properties:
         "strikeout": {"type": "boolean"},
         "style": {
             "type": "string",
-            "enum": ["classic", "karaoke", "highlight", "underline", "word_by_word"]
+            "enum": [
+                "classic",     // Regular captioning with all text displayed at once
+                "karaoke",     // Highlights words sequentially in a karaoke style
+                "highlight",   // Shows full text but highlights the current word
+                "underline",   // Shows full text but underlines the current word
+                "word_by_word" // Shows one word at a time
+            ]
         },
         "outline_width": {"type": "integer"},
         "spacing": {"type": "integer"},
@@ -71,38 +81,62 @@ The request body must be a JSON object with the following properties:
 }
 ```
 
-### Example Request
+### Example Requests
+
+#### Example 1: Basic Automatic Captioning
+```json
+{
+    "video_url": "https://example.com/video.mp4"
+}
+```
+This minimal request will automatically transcribe the video and add white captions at the bottom center.
 
+#### Example 2: Custom Text with Styling
 ```json
 {
     "video_url": "https://example.com/video.mp4",
     "captions": "This is a sample caption text.",
+    "settings": {
+        "style": "classic",
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "alignment": "center",
+        "font_family": "Arial",
+        "font_size": 24,
+        "bold": true
+    }
+}
+```
+
+#### Example 3: Karaoke-Style Captions with Advanced Options
+```json
+{
+    "video_url": "https://example.com/video.mp4",
     "settings": {
         "line_color": "#FFFFFF",
-        "word_color": "#000000",
+        "word_color": "#FFFF00",
         "outline_color": "#000000",
         "all_caps": false,
         "max_words_per_line": 10,
-        "x": 20,
-        "y": 40,
-        "position": "bottom_left",
-        "alignment": "left",
+        "position": "bottom_center",
+        "alignment": "center",
         "font_family": "Arial",
         "font_size": 24,
         "bold": false,
         "italic": false,
-        "underline": false,
-        "strikeout": false,
-        "style": "classic",
+        "style": "karaoke",
         "outline_width": 2,
-        "spacing": 2,
-        "angle": 0,
         "shadow_offset": 2
     },
     "replace": [
         {
-            "find": "sample",
-            "replace": "example"
+            "find": "um",
+            "replace": ""
+        },
+        {
+            "find": "like",
+            "replace": ""
         }
     ],
     "webhook_url": "https://example.com/webhook",
@@ -111,44 +145,47 @@ The request body must be a JSON object with the following properties:
 }
 ```
 
+#### Example 4: Using an External Subtitle File
+```json
+{
+    "video_url": "https://example.com/video.mp4",
+    "captions": "https://example.com/subtitles.srt",
+    "settings": {
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "font_family": "Arial",
+        "font_size": 24
+    }
+}
+```
+
 ```bash
 curl -X POST \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
         "video_url": "https://example.com/video.mp4",
-        "captions": "This is a sample caption text.",
         "settings": {
             "line_color": "#FFFFFF",
-            "word_color": "#000000",
+            "word_color": "#FFFF00",
             "outline_color": "#000000",
             "all_caps": false,
             "max_words_per_line": 10,
-            "x": 20,
-            "y": 40,
-            "position": "bottom_left",
-            "alignment": "left",
+            "position": "bottom_center",
+            "alignment": "center",
             "font_family": "Arial",
             "font_size": 24,
-            "bold": false,
-            "italic": false,
-            "underline": false,
-            "strikeout": false,
-            "style": "classic",
-            "outline_width": 2,
-            "spacing": 2,
-            "angle": 0,
-            "shadow_offset": 2
+            "style": "karaoke",
+            "outline_width": 2
         },
         "replace": [
             {
-                "find": "sample",
-                "replace": "example"
+                "find": "um",
+                "replace": ""
             }
         ],
-        "webhook_url": "https://example.com/webhook",
-        "id": "request-123",
-        "language": "en"
+        "id": "custom-request-id"
     }' \
     https://your-api-endpoint.com/v1/video/caption
 ```
@@ -255,13 +292,28 @@ Additionally, the main application context (`app.py`) includes error handling fo
 
 ## 6. Usage Notes
 
-- The `video_url` parameter must be a valid URL pointing to a video file.
-- The `captions` parameter is optional. If not provided, the video will be returned without captions.
-- The `settings` parameter allows for customization of the caption appearance and behavior.
-- The `replace` parameter can be used to perform text replacements in the captions.
+- The `video_url` parameter must be a valid URL pointing to a video file (MP4, MOV, etc.).
+- The `captions` parameter is optional and can be used in multiple ways:
+  - If not provided, the endpoint will automatically transcribe the audio and generate captions
+  - If provided as plain text, the text will be used as captions for the entire video
+  - If provided as a URL to an SRT or ASS subtitle file, the system will use that file for captioning
+  - For SRT files, only 'classic' style is supported
+  - For ASS files, the original styling will be preserved
+- The `settings` parameter allows for customization of the caption appearance and behavior:
+  - `style` determines how captions are displayed, with options including:
+    - `classic`: Regular captioning with all text displayed at once
+    - `karaoke`: Highlights words sequentially in a karaoke style as they're spoken
+    - `highlight`: Shows the full caption text but highlights each word as it's spoken
+    - `underline`: Shows the full caption text but underlines each word as it's spoken
+    - `word_by_word`: Shows only one word at a time
+  - `position` can be used to place captions in one of nine positions on the screen
+  - `alignment` determines text alignment within the position (left, center, right)
+  - `font_family` can be any available system font
+  - Color options can be set using hex codes (e.g., "#FFFFFF" for white)
+- The `replace` parameter can be used to perform text replacements in the captions (useful for correcting words or censoring content).
 - The `webhook_url` parameter is optional and can be used to receive a notification when the captioning process is complete.
-- The `id` parameter is optional and can be used to identify the request.
-- The `language` parameter is optional and can be used to specify the language of the captions. If not provided, the language will be automatically detected.
+- The `id` parameter is optional and can be used to identify the request in webhook responses.
+- The `language` parameter is optional and can be used to specify the language of the captions for transcription. If not provided, the language will be automatically detected.
 
 ## 7. Common Issues