הגדרת כתוביות שנוצרות אוטומטית

בדף הזה מוסבר איך להוסיף כתוביות שנוצרו באופן אוטומטי לפלט באמצעות Transcoder API. התכונה הזו מאפשרת לכם ליצור כתוביות מטראקים של אודיו, גם אם השפה לא ידועה, ולתרגם כתוביות לשפות שונות.

כדי להגדיר את התכונה הזו, צריך לספק מטא-נתונים נוספים על נכסי הקלט באמצעות השדה attributes בכל פריט במערך inputs בהגדרת העבודה. השדה הזה עוזר ל-Transcoder API להבין את השפות שמופיעות בפסקולי האודיו ואת אופן העיבוד שלהן.

לפני שמתחילים

במאמר הזה אנחנו מניחים שביצעתם את השלבים בקטע לפני שמתחילים.

מגבלות

יש לתכונה הזו את המגבלות הבאות:

מיקומים נתמכים

התכונה הזו נתמכת ב-us-central1 וב-europe-west4.

פורמט פלט

הפלט של כתוביות שנוצרו באופן אוטומטי צריך להיות בפורמט WebVTT ‏ (webvtt).

עריכת רשימת התפירה

התכונה הזו לא תומכת בשימוש ב-editList כדי לחבר כמה קטעי וידאו.

דוגמאות להגדרות

בדוגמאות הבאות מוסבר איך להגדיר כתוביות אוטומטיות למגוון תרחישי שימוש.

מיפוי שהמשתמשים סיפקו

השיטה הזו מאפשרת שליטה ישירה, כי אפשר לציין בדיוק באיזה טראק קלט להשתמש כדי ליצור כתוביות.

מיפוי מפורש של טראקים של קלט לזרמי כתוביות של פלט

בדוגמה הזו אנחנו מראים איך להשתמש בשדה mapping בכל textStream כדי לשלוט בדיוק באיזה טראק אודיו של קלט ישמש ליצירת כתוביות באנגלית ובצרפתית.

{
  "config": {
    "inputs": [
      {
        "key": "input0",
        "uri": "gs://input-bucket/input.mp4",
        "attributes": {
          "trackDefinitions": [
            {
              "inputTrack": 1,
              "languages": [
                "en-US"
              ]
            },
            {
              "inputTrack": 2,
              "languages": [
                "fr-FR"
              ]
            }
          ]
        }
      }
    ],
    "editList": [
      {
        "key": "atom0",
        "inputs": [
          "input0"
        ]
      }
    ],
    "elementaryStreams": [
      {
        "key": "video-stream0",
        "videoStream": {
          "h264": {
            "frameRate": 30,
            "widthPixels": 1280,
            "heightPixels": 720,
            "bitrateBps": 3200000,
            "frameRateConversionStrategy": "DOWNSAMPLE"
          }
        }
      },
      {
        "key": "audio-stream0",
        "audioStream": {
          "codec": "aac",
          "bitrateBps": 64000,
          "sampleRateHertz": 48000,
          "channelCount": 2,
          "channelLayout": [
            "fl",
            "fr"
          ]
        }
      },
      {
        "key": "vtt-stream-english",
        "textStream": {
          "codec": "webvtt",
          "languageCode": "en-US",
          "displayName": "English",
          "mapping": [
            {
              "atomKey": "atom0",
              "inputKey": "input0",
              "inputTrack": 1
            }
          ]
        }
      },
      {
        "key": "vtt-stream-french",
        "textStream": {
          "codec": "webvtt",
          "languageCode": "fr-FR",
          "displayName": "French",
          "mapping": [
            {
              "atomKey": "atom0",
              "inputKey": "input0",
              "inputTrack": 2
            }
          ]
        }
      }
    ],
    "muxStreams": [
      {
        "container": "fmp4",
        "elementaryStreams": [
          "video-stream0"
        ],
        "fileName": "video-only.m4s",
        "key": "hd-video-only",
        "segmentSettings": {
          "segmentDuration": "6s"
        }
      },
      {
        "container": "fmp4",
        "elementaryStreams": [
          "audio-stream0"
        ],
        "fileName": "audio-only.m4s",
        "key": "audio-only",
        "segmentSettings": {
          "segmentDuration": "6s"
        }
      },
      {
        "key": "text-vtt-english",
        "container": "vtt",
        "elementaryStreams": [
          "vtt-stream-english"
        ],
        "segmentSettings": {
          "individualSegments": true,
          "segmentDuration": "6s"
        }
      },
      {
        "key": "text-vtt-french",
        "container": "vtt",
        "elementaryStreams": [
          "vtt-stream-french"
        ],
        "segmentSettings": {
          "individualSegments": true,
          "segmentDuration": "6s"
        }
      }
    ],
    "manifests": [
      {
        "fileName": "manifest.m3u8",
        "muxStreams": [
          "hd-video-only",
          "audio-only",
          "text-vtt-english",
          "text-vtt-french"
        ],
        "type": "HLS"
      }
    ],
    "output": {
      "uri": "gs://your-bucket/output/"
    }
  }
}

הסטרימינג vtt-stream-english נוצר מטראק 1 של input0 בגלל המיפוי המפורש. הזרם vtt-stream-french נוצר מתוך טראק 2 של input0.

מיפוי ברירת מחדל באמצעות Transcoder API

בדוגמאות האלה נעשה שימוש ב-API כדי להסיק באיזה טראק אודיו להשתמש על סמך attributes שצוין ב-inputs. ההנחה היא שהחלקים האחרים של ההגדרה (muxStreams, manifests, output) דומים לדוגמה המלאה.

טראק אודיו יחיד בשפה ידועה

אם לסרטון הקלט יש טראק אודיו אחד (לדוגמה, טראק 1) ואתם יודעים שהוא באנגלית (en-US), אתם יכולים ליצור כתוביות באנגלית. אפשר גם לבקש כתוביות בשפות אחרות, כמו צרפתית (fr-FR), וה-API יתרגם את התמליל באנגלית.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "inputTrack": 1,
            "languages": [
              "en-US"
            ]
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-english",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "en-US",
        "displayName": "English"
      }
    },
    {
      "key": "vtt-stream-french",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "fr-FR",
        "displayName": "French"
      }
    }
  ]
}

הסטרימינג של הכתוביות באנגלית (vtt-stream-english) נוצר ישירות מטראק האודיו 1 שהוגדר, כי קודי השפה זהים. טראק הכתוביות בצרפתית (vtt-stream-french) נוצר על ידי תמלול האודיו באנגלית מטראק 1, ולאחר מכן תרגום הטקסט שנוצר לצרפתית.

כמה טראקים של אודיו בשפות ידועות

אם קובץ הקלט מכיל כמה טראקים של אודיו בשפות שונות (למשל, צרפתית בטראק 1 ואנגלית בטראק 2), אפשר לציין את השפות של כל טראק.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "inputTrack": 1,
            "languages": ["fr-FR"]
          },
          {
            "inputTrack": 2,
            "languages": ["en-US"]
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-english",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "en-US",
        "displayName": "English"
      }
    },
    {
      "key": "vtt-stream-french",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "fr-FR",
        "displayName": "French"
      }
    }
  ]
}

בהגדרה הזו, הכתוביות vtt-stream-english נוצרות מטראק אודיו 2, והכתוביות vtt-stream-french נוצרות מטראק אודיו 1, על סמך קודי השפה שמופיעים ב-attributes.

שפת הפלט לא תואמת לאף טראק אודיו של הקלט

אם שפת הכתוביות המבוקשת לא תואמת לאף אחת מהשפות שהוגדרו לטראקים, ה-API משתמש בטראק האודיו הזמין הראשון לתמלול ולתרגום.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "inputTrack": 1,
            "languages": ["fr-FR"]
          },
          {
            "inputTrack": 2,
            "languages": ["en-US"]
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-hindi",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "hi-IN",
        "displayName": "Hindi"
      }
    }
  ]
}

מכיוון שלא הוגדר טראק אודיו בהינדית, הכתוביות vtt-stream-hindi נוצרות על ידי תמלול של טראק האודיו הראשון (טראק 1, צרפתית) ולאחר מכן תרגום התמלול להינדית.

טראק אודיו יחיד עם שילוב של שפות

אם טראק אודיו אחד מכיל כמה שפות, יש לציין את כולן במערך languages.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "inputTrack": 1,
            "languages": ["en-US", "fr-FR"]
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-english",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "en-US",
        "displayName": "English"
      }
    },
    {
      "key": "vtt-stream-french",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "fr-FR",
        "displayName": "French"
      }
    },
    {
      "key": "vtt-stream-hindi",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "hi-IN",
        "displayName": "Hindi"
      }
    }
  ]
}

כל שלושת הסטרימינג של VTT (אנגלית, צרפתית והינדי) נוצרים מתוך טראק האודיו 1. ה-API יתמלל את האודיו בשפות המעורבות ויספק כל זרם פלט בשפה היחידה שצוינה בשדה languageCode.

ה-API מתמלל את האודיו, ויכול לזהות כמה שפות בטראק 1. לכל פלט textStream, המערכת יוצרת כתוביות רק בשפה שצוינה בשדה languageCode של הזרם הזה.

זיהוי שפה בטראק אודיו ספציפי

משתמשים בערך detectLanguages": true כשלא יודעים את השפה של טראק מסוים.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "inputTrack": 1,
            "detectLanguages": true
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-english",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "en-US",
        "displayName": "English"
      }
    }
  ]
}

ה-API מזהה קודם את השפות שמופיעות בטראק אודיו 1. לאחר מכן המערכת יוצרת את הכתוביות באנגלית, כולל תרגום אם השפה שזוהתה היא לא אנגלית.

זיהוי שפה בטראק האודיו שמוגדר כברירת מחדל

אם השפה ומספר הטראק לא ידועים, ה-API משתמש כברירת מחדל בטראק האודיו הראשון שזמין.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "detectLanguages": true
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-english",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "en-US",
        "displayName": "English"
      }
    }
  ]
}

ה-API מנתח את טראק האודיו הראשון כדי לזהות את השפות, ואז יוצר את הכתוביות באנגלית, ומתרגם אותן אם צריך.

ציון שפה לטראק האודיו שמוגדר כברירת מחדל

אם אתם יודעים את השפה אבל לא את מספר הטראק הספציפי, ה-API מניח שטראק האודיו הראשון שזמין תואם לשפה שצוינה.

{
  "inputs": [
    {
      "key": "input0",
      "uri": "gs://input-bucket/input.mp4",
      "attributes": {
        "trackDefinitions": [
          {
            "languages": ["en-US"]
          }
        ]
      }
    }
  ],
  "elementaryStreams": [
    { "key": "video-stream0", "videoStream": { ... } },
    { "key": "audio-stream0", "audioStream": { ... } },
    {
      "key": "vtt-stream-english",
      "textStream": {
        "codec": "webvtt",
        "languageCode": "en-US",
        "displayName": "English"
      }
    }
  ]
}

הכתוביות באנגלית (vtt-stream-english) נוצרות מהטראק הראשון של האודיו בקלט, מתוך הנחה שהטראק הזה הוא באנגלית.

שאלות נפוצות

מה קורה אם מציינים גם את languages וגם את detectLanguages באותו trackDefinition?

אפשר לציין רק אחד מהשדות languages או detectLanguages בתוך trackDefinition אחד. הוספת שניהם באותה הגדרה היא הגדרה לא תקינה ותגרום לשגיאה.

איך ה-API בוחר באיזה טראק אודיו להשתמש אם כמה טראקים של trackDefinitions תואמים לשפה של textStream?

אם יש לכם כמה רכיבי trackDefinitions במערך inputs.attributes.trackDefinitions שיכולים להתאים לערך languageCode של textStream שמתבקש, ה-API ישתמש בטראק האודיו מהרכיב הראשון התואם trackDefinition בסדר המערך. ההגדרה הזו חלה רק כשלא משתמשים בשדה mapping המפורש בתוך textStream.