استفاده از API ترنسکد ویدئو
از آنجا که سرویس VoD بر بستر Kubernetes اسقرار یافته و برای تعریف API و موجودیتهای سیستم از CRD های کوبرنتیز استفاده شده، برای اتصال و استفاده از سرویس نیاز به ابزار kubectl برای برقراری ارتباط با کلاستر Kubernetes ما وجود دارد. جهت اتصال و استفاده از سرویس میتوانید از kubectl استفاده کنید. همچنین برای اتصال و ارتباط با کلاستر از طریق کد، کتابخانههای متعددی برای زبانهای برنامهنویسی مختلف توسعه داده شده است که از جمله آنها میتوان به client-go که برای زبان برنامهنویسی Go توسعه داده شده است اشاره کرد.
برای استفاده از kubectl نیاز به یک فایل پیکربندی وجود دارد که محتویات آن را در کادر صفحه بعد مشاهده میکنید.
برای دریافت توکن بپا یا bepa-token در پنل اوشن مطابق تصویر زیر و در قسمت توکنهای کاربر در صفحه پروفایل خود بر روی دکمه افزودن توکن کاربر کلیک کرده و پس از انتخاب یک نام دلخواه اقدام به دریافت توکن کنید.
جهت استفاده از سرویس کاربر باید دسترسی ساخت تبدیلها (transcodes) و اجزای دیگر سرویس نظیر presetها و piplineها را داشته باشد. برای این منظور از کاربری که بر روی workspace شما نقش مستر را دارد و یا به عبارتی workspace-master است بخواهید که از قسمت نقشها در صفحه تنظیمات بپا شما رو به نقشهای زیر اضافه کند:
- workspace-user
- transcodes-admin
- pipelines-admin
- presets-admin
چنانچه به دسترسی ایجاد تبدیل نیازی نداشته باشید و فقط قصد مشاهده تبدیلها را دارید به جای admin از معادلهای viewer هم میتوانید استفاده کنید:
- transcode-viewer
- pipline-viewer
- preset-viewer
در ادامه برخی از دستورات پر کاربرد در استفاده از سرویس VoD را شرح میدهیم:
برای اعمال یا به اصطلاح apply کردن یک فایل manifest که معمولا به صورت yaml میباشند، میتوانید از دستور زیر استفاده کنید. در صورتی که در فایل پیکربندی مقدار current-context برای کلاستر ما ست شده باشد نیازی به آپشن context-- نیست. همچنین اگر namespace در فایل پیکربندی به namespace ایجاد شده در کلاستر ما اشاره کند به آپشن n- هم نیازی ندارید.
برای این منظور از دستور get استفاده میکنیم که در ادامه نمونهای از آن برای دریافت تمام manifestهای از نوع pod مشاهده میکنید:
البته برای استفاده از سرویس VOD موجودیتهایی نظیر transcode, pipline و preset را تعریف نمودهایم که در ادامه هر یک به تفضیل شرح داده خواهند شد. مثلا برای نمایش همه transcodeهای موجود در namespace شما میتوانید از دستور زیر استفاده کنید:
برای این منظور کافیست که نام موجودیت را در مقابل دستور قبلی قرار دهید. به عنوان مثال دستور زیر موجودیت sample را از نوع preset نمایش میدهد:
در صورتی که از آپشن o yaml- استفاده کنید میتوانید اطلاعات کامل را به صورت yaml مشاهده کنید:
اگر برای ذخیره فایل چندرسانهای ورودی از سرویس S3 ستون یا همان کیسه استفاده میکنید باید دسترسی خواندن از روی باکت خود را برای سرویس VoD ایجاد کنید. برای این منظور کافی است که در صفحه باکت خود که در بخش سرویس کیسه میتوانید مشاهده کنید، بر روی تب باکت پالیسی کلیک کنید و سپس دکمه ویرایش پالیسی را فشار دهید و سپس مقدار زیر را در کادر مربوطه وارد کرده و ذخیره کنید.
یک Transcode بیانگر یک Job تبدیل یک منبع چندرسانهای به چندین خروجی، پلیلیست و همچنین thumbnailها است. برای ایجاد یک Transcode باید manifestای مشابه فایل زیر ساخته و روی APIServer (از طریق kubectl یا کتابخانه درون کد) اپلای کنید.
مقادیر apiVersion و kind را مطابق جدول زیر تعیین کنید. (رعایت کوچک و بزرگ بودن حروف مهم است):
Field | Type | Value | Mandatory |
---|---|---|---|
apiVersion | string | delivery.ravh.ir/v1 | Yes |
kind | string | Transcode | Yes |
metadata
در قسمت metadata.name میتوانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید:
Field | Type | Value | Mandatory |
---|---|---|---|
name | string | According to RFC 1123 | Yes |
namespace | string | According to RFC 1123 | No |
spec
این قسمت به ۳ بخش input, output و pipelineName تقسیم میشود که در ادامه جزییات هر یک به تفضیل شرح داده شده است:
Field | Type | Description | Mandatory |
---|---|---|---|
input | object | تنظیمات s3 و فایل ورودی برای تبدیل | Yes |
output | object | مشخصات خروجی تبدیل شده | Yes |
pipelineName | string | رفرنس به تعریف pipeline (مشخصات تبدیل) | No |
pipelineSpec | object | در صورت تمایل، میتوانید به جای ست کردن نام و اشارهگر به پایپلاین از پیش ساخته شده با استفاده از فیلد pipelineName، از این فیلد استفاده کنید و فیلدهای مربوط به pipeline را به صورت inline در manifest ترانسکد وارد کنید. | No |
توجه: فیلدهای pipelineName و pipelineSpec هر کدام به تنهایی الزامی نمیباشند ولی حداقل یکی از این دو فیلد باید داخل transcode spec ست شده باشد. در صورتی که هیچ یک از این دو فیلد مقدار معتبر نداشته باشند، api ارور validation برمیگرداند.
spec.input
این قسمت شامل مشخصات فایل ورودی است که میخواهید عملیات Transcode بر روی آن انجام شود. در نظر داشته باشید که عرض و ارتفاع ویدئو استریم مشخص شده در این قسمت از تنظیمات دارای محدودیت هستند. به این صورت که مقدار ماکسیمم عرض و ارتفاع ویدئو استریم ورودی از ۱۹۲۰ پیکسل باید کمتر باشد. همچنین، مقدار مینیمم عرض و ارتفاع ویدئو استریم ورودی از ۱۰۸۰ پیکسل باید کمتر باشد.
در حال حاضر فقط از یک نوع input پشتیبانی میشود، جزئیات این فیلد در ادامه شرح داده شده است:
Field | Type | Description | Mandatory |
---|---|---|---|
protocol | string | در حال حاضر فقط s3 پشتیبانی میشود | Yes |
s3 | object | مشخصات s3 endpoint و باکت و نام آبجکت | Yes |
Field | Type | Description | Mandatory |
endpoint | object | مشخصات s3 endpoint برای دریافت فایل ورودی | Yes |
bucket | string | اسم باکتی که فایل داخل آن است | Yes |
object | string | آدرس یا prefix فایل داخل باکت | Yes |
Field | Type | Description | Mandatory |
---|---|---|---|
kise | boolean | آیا فایل ورودی روی کیسه ذخیره شده است؟ | Yes |
address | string | آدرس endpoint سرویس S3 | Yes |
accessKey | string | کلید دسترسی (در صورتی که ازs3 غیر از کیسه استفاده میکنید) | No |
secretKey | string | کلید مخفی (در صورتی که ازs3 غیر از کیسه استفاده میکنید) | No |
spec.output
مشخصات محل ذخیره فایلهای خروجی که روی باکتی در کیسه ذخیره میشود. برای هر workspace و کاربر یک باکت ساخته میشود که نام آن در قسمت status در manifest ترانسکد درج میشود. نام این باکت ترکیبی است از workspaceId و userId که در این قسمت از کاربر گرفته میشود.
توجه: برای دریافت فایلها کافیست از یک کلاینت استاندارد s3 نظیر aws-cli استفاده کنید و با access-key و secret-key خود به این endpoint متصل شوید و فایلها را از باکتی که در قسمت status از manifest ترانسکد مشخص شده، دریافت کنید.
نحوه به دست آوردن workspaceId
برای این منظور از طریق پنل اوشن و در صفحه تنظیمات بپا و قسمت فضای کاری، workspace خود را جستجو کنید و شناسه خود را دریافت کنید.
نحوه به دست آوردن access key, secret key و userId
برای این منظور باید در پنل اوشن workspace خود یک کاربر سرویس یا همان service user داشته باشید و از شناسهی این کاربر سرویس به عنوان userId ترانسکد خود استفاده کنید. در صورت عدم وجود کاربر سرویس، برای ساخت آن، در قسمت بپای پنل اوشن میتوانید کاربر سرویس مورد نظر خود بسازید. در این قسمت در ویزارد ساخت سرویس کاربر، نیازی به اساین کردن نقش به سرویس کاربر مورد نظر نمیباشد.
پس از ساخت کاربر سرویس، در قسمت کلیدهای اتصال پنل کیسه، تب کلیدهای اتصال کاربر سرویس یک کلید اتصال جدید بسازید.
در ادامه میتوانید به مقادیر شناسهی سرویس کاربر و access key و secret key کلیدهای سرویس کاربر مورد نظر دسترسی داشته باشید.
Field | Type | Description | Mandatory |
---|---|---|---|
workspaceId | string | مشخصه workspace که از طریق پنل اوشن و قسمت بپا قابل دسترسی میباشد. | Yes |
userId | string | شناسهی service user که از طریق پنل اوشن و قسمت بپا قابل ساخت و دسترسی میباشد. | Yes |
prefix | string | مسیر ذخیره فایل در باکت که میتواند به صورت x/y/z باشد. توجه کنید که در صورتی که مسیر تکراری برای دو ترانسکد وارد کنید، فایلهای ترانسکد دوم، روی مسیر ترانسکد اول overwrite خواهند شد، در صورتی که این فیلد را پر نکرده باشید یک مقدار به صورت تصادفی ساخته خواهد شد. | No |
spec.pipelineName
هر ترانسکد نیاز به یک پایپلاین برای تعریف خروجیهای مختلف، کیفیتها، پلیلیستها و thumbnailها دارد. که رفرنس این pipeline در این فیلد ذخیره خواهد شد. به عبارتی دیگر اگر مقدار این فیلد x باشد حتما باید یک pipeline با نام x در namespace شما وجود داشته باشد.
توجه: چنانچه مایل باشید میتوانید به جای استفاده از pipelineName از pipelineSpec استفاده کنید. و
فیلدهای مربوط به pipeline را به صورت inline در manifest ترانسکد وارد کنید.
:Status
بیانگر آخرین وضعیت یک transcode ساخته شده است که در واقع یک آبجکت است. در ادامه به فیلدهای این آبجکت اشاره میکنیم:
Description | Type | Field |
این فیلد نمایش دهندهی آخرین وضعیت transcode مورد نظر است. حالتهای مختلف این وضعیت در جدول بعد آورده شده است. | string | state |
این فیلد نمایش دهندهی میزان پیشرفت transcode استریمهای ورودی به صورت درصدی است. | string | progress |
این فیلد نمایشدهندهی سرعت فرایند transcode استریمهای ورودی میباشد که در واقع نسبت طول زمانی استریمهای ورودی به میزان زمان طی شده برای انجام فرایند transcode است. | string | speed |
این فیلد نمایشدهندهی اسم bucketای است که خروجیهای transcode در آن قرار گرفتهاند. | string | outputBucket |
مقدار این فیلد prefix همهی آبجکتهای آپلود شده در باکت خروجی است. | string | outputPrefix |
در صورتی که وضعیت transcode مورد نظر در حالت Failed باشد و در واقع این فرایند fail شده باشد، این فیلد جهت نمایش علت و توضیحات بیشتر در موردش ارور پیشآمده است.در صورتی که transcode با موفقیت انجام شده باشد، این فیلد شامل آدرس cdn سرو خروجیهای transcode است. | string | message |
Description | State |
---|---|
این وضعیت که حالت اولیهی state machine ترانسکد میباشد، نشاندهندهی این است که جاب ترانسکد schedule شده و به زودی transcode آن شروع میشود. | Scheduled |
در این وضعیت، مقدمات و فرایندهای پیش نیاز transcode در حال اجرا میباشند. | Preparing |
در این وضعیت، استریمهای ورودی transcode در حال دانلود میباشند. | Downloading |
در این وضعیت، استریمهای ورودی دانلود شدهاند و خود فرایند transcode در حال انجام است. در این حالت، با استفاده از فیلد progress، میتوانید میزان پیشرفت فرایند را مشاهده کنید. | Transcoding |
در این وضعیت، فرایند transcode و همچنین آپلود خروجیها در کیسه انجام شده و باکت و آبجکتهای مورد نظر ترانسکد در دسترس و قابل استفاده میباشند. در این وضعیت، مقدار فیلد message در status شامل آدرس cdn مورد نیاز برای سرو خروجیهای ترانسکد میباشد. | Completed |
یک Pipeline بیانگر مسیری است که فایلهای ورودی برای تبدیل شدن به خروجی طی میکنند. تعداد خروجیها و نام و پیکربندی آنها، تعریف playlist برای استفاده در پخش استریمینگ و همچنین تعریف نحوه تولید thumbnail هاست. میتوانید برای تسریع کار به جای تعریف Pipeline به ازای هر بار ایجاد یک Transcode Job، یک بار Pipeline مدنظرتان را بسازید و آن را reuse کنید.
در ادامه نمونهای از manifest یک pipeline را مشاهده میکنید:
مقادیر apiVersion و kind را مطابق جدول زیر تعیین کنید. (رعایت کوچک و بزرگ بودن حروف مهم است):
Field | Type | Value | Mandatory |
---|---|---|---|
apiVersion | string | delivery.ravh.ir/v1 | Yes |
kind | string | Transcode | Yes |
metadata
در قسمت metadata.name میتوانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید:
Field | Type | Value | Mandatory |
---|---|---|---|
name | string | According to RFC 1123 | Yes |
namespace | string | According to RFC 1123 | No |
spec
این قسمت به ۳ بخش playlist, outputs و thumbs تقسیم میشود که در ادامه جزییات هر یک به تفضیل شرح داده شده است:
Field | Type | Description | Mandatory |
---|---|---|---|
outputs | []object | لیست خروجیها (کیفیت صدا و تصویر) | Yes |
playlist | object | در صورت درخواست ایجاد playlist از فایلهای خروجی باید این قسمت پیکربندی شود | No |
thumbs | object | در صورت درخواست تولید فایلهای thumbnail با فاصلههای زمانی مشخص، از فایلهای خروجی این قسمت باید پیکربندی شود | No |
spec.outputs
در قسمت spec.outputs، ما لیستی از output های مختلفی را که میخواهیم تولید شود، تعریف میکنیم. برای این کار از تنظیمات زیر به ازای هر output استفاده میکنیم.
Field | Type | Description | Mandatory |
---|---|---|---|
key | string (unique in list) | یک نام یکتا که به این تعریف خروجی نسبت میدهید | Yes |
presetName | string | نام آبجکت Preset ای که تعریف صوت و تصویر این خروجی از روی آن خوانده میشود. در ادامه نحوه تعریف یک Preset توضیح داده خواهد شد. | No |
excludeFromPlaylist | bool | در صورتی که میخواهید این خروجی به playlist اضافه نشود، این گزینه را true کنید | No |
excludeFromThumbs | bool | در صورتی که میخواهید برای این خروجی thumbs ساخته نشود، این گزینه را true کنید | No |
presetSpec | object | در صورت تمایل، میتوانید به جای ست کردن presetName، از این فیلد استفاده کنید و فیلدهای مربوط به preset را به صورت inline در manifest پایپلاین وارد کنید. | No |
توجه: فیلدهای presetName و presetSpec هر کدام به تنهایی الزامی نمیباشند ولی حداقل یکی از این دو فیلد باید داخل pipeline spec ست شده باشد. در صورتی که هیچ یک از این دو فیلد مقدار معتبر نداشته باشند api ارور validation برمیگرداند.
spec.playlist
پلیلیست یک پروتکل استریم انطباقی است که قابلیت پخش یک فایل چندرسانهای را بر بستر http فراهم میکند از معروفترین این پروتکلها میتوان به HLS و DASH اشاره کرد. در ادامه فیلدهای مربوط به قسمت playlist شرح داده میشوند:
Field | Type | Description | Mandatory |
---|---|---|---|
enabled | bool | آیا این playlist فعال است یا خیر | Yes |
name | string | نامی که میخواهید playlist تان داشته باشد | Yes |
format | string | فرمت playlist در حال حاضر فقط hls پشتیبانی میشود | Yes |
hls | object | پیکربندی hls | Yes |
Field | Type | Description | Mandatory |
---|---|---|---|
segmentDuration | int | زمان تقریبی هر سگمنت را مشخص میکند | Yes |
spec.thumbs
تصویر بندانگشتی (Thumbnail) به تصاویر کوچکی گفته میشود که از روی یک تصویر اصلی یا فریمی از یک ویدیو ایجاد میشود و معمولا به کاربر در یافتن محتوای تصویری مورد نظر خود در میان انبوهی از تصاویر و ویدیوها کمک میکند.
Field | Type | Description | Mandatory |
---|---|---|---|
format | string | فرمت تصاویر میتواند jpg یا png باشد | Yes |
interval | uint | زمان بین عکسها به ثانیه | Yes |
یک Preset بیانگر کیفیت صدا و تصویر یک خروجی مشخص شده در پایپلاین است. اینکه codec صوت و تصویر، frameRate و bitrate و سایر تنظیمات چه باشد. اینجا هم برای راحتی کار و تسریع ایجاد Job میتوانید Presetهایی از قبل تعریف کنید و در تعریف Pipeline از آن استفاده کنید.
در ادامه نمونهای از manifest یک preset را مشاهده میکنید:
مقادیر apiVersion و kind را مطابق جدول زیر تعیین کنید. (رعایت کوچک و بزرگ بودن حروف مهم است):
Field | Type | Value | Mandatory |
---|---|---|---|
apiVersion | string | delivery.ravh.ir/v1 | Yes |
kind | string | Transcode | Yes |
metadata
در قسمت metadata.name میتوانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید:
Field | Type | Value | Mandatory |
---|---|---|---|
name | string | According to RFC 1123 | Yes |
namespace | string | According to RFC 1123 | No |
Field | Type | Description | Mandatory |
---|---|---|---|
description | string | توضیح دلخواه در مورد این پیکربندی | No |
container | string | فرمت فایل نهایی تولیدی، میتواند یکی از مقادیر mp4، m4v، mov و یا avi باشد. | Yes |
speed | string | سرعت تبدیل، میتواند medium، veryfast و ultrafast باشد. مقدار توصیه شده استفاده از veryfast است که هم سرعت و هم کیفیت خوبی در خروجی دارد. | No |
skipAudio | bool | در صورتی که میخواهید کانال صدا از خروجی حذف شود این فیلد را true کنید. | Yes |
skipVideo | bool | در صورتی که میخواهید کانالهای تصویر از خروجی حذف شود این فیلد را true کنید. توجه کنید که هر دو فیلد skipAudio و skipVideo نمیتوانند همزمان true باشند. | Yes |
audio | object | تنظیمات صدا | Yes |
video | object | تنظیمات تصویر | Yes |
Field | Type | Description | Mandatory |
---|---|---|---|
codec | string | نوع کدک صدا را مشخص میکند. میتواند یکی از مقادیرaac, mp3, vorbis, opus, copy باشد. مقدار copy به معنای کپی کردن کدک ورودی در خروجی بدون تغییر است | Yes |
bitrate | string | نرخ استریم صدا را مشخص میکند. میتوان مقادیری چون 100، 1k، و 1m به آن نسبت داد. در یک کدک ثابت بیتریت بالاتر به معنی کیفیت بالاتر است | No |
sampleRate | uint | نرخ نمونهبرداری از صدای ورودی برای تولید صدای خروجی است و میتواند یکی از مقادیر زیر باشد22050 ,32000 ,44100 ,48000 ,96000 | No |
Field | Type | Description | Mandatory |
codec | string | نوع کدک تصویر را مشخص میکند. میتواند یکی از مقادیر h264،h265 و یا vp9 باشد. | Yes |
resizeType | string | این فیلد روش تغییر طول و عرض تصویر را مشخص میکند و میتواند یکی از مقادیر unconstrained یا percentage یا autoWidth و یا autoHeight باشد که در ادامه هریک توضیح داده شده: :unconstrained محدودیتی در تعیین اندازه طول و عرض تصویر نبوده و میتوانید مقدار دلخواه را برای طول و عرض تصویر مشخص کنید:percentage نسبت طول و عرض تصویر حفظ شده و به میزانی که در فیلد percentage گفته شده تصویر بزرگ یا کوچک میشود.:autoWidthنسبت تصویر حفظ میشود اما مقدار height گرفته میشود و بر مبنای آن width تغییر میکند.autoHeightنسبت تصویر حفظ میشود اما مقدار width گرفته میشود و بر مبنای آن height تغییر میکند. | Yes |
width | uint | عرض تصویر به پیکسل. حداکثر اندازهی عرض تصویر ۱۹۲۰ پیکسل میباشد. (لطفا توضیحات شماره ۱ مطالعه شود.) | No |
height | uint | ارتفاع تصویر به پیکسل. حداکثر اندازهی ارتفاع تصویر ۱۹۲۰ پیکسل میباشد. (لطفا توضیحات شماره ۱ مطالعه شود.) | No |
percentage | uint | درصد بزرگنمایی در حالتی که resizeType روی حالت percentage تنظیم شده باشد. حداکثر 1000 | No |
frameRate | uint | نرخ تصویر در ثانیه، حداکثر 120 | No |
bitrate | string | نرخ متوسط استریم تصویر را مشخص میکند. مقدار این فیلد میتواند یک عدد بدون واحد (مثلا 120) یا عدد همراه با واحد باشد (1m یا 2k) که m به معنای میلیون و k به معنای هزار است. در یک کدک ثابت، بیتریت بالاتر به معنی کیفیت بالاتر است. این مقدار لزوما بیتریت خروجی نیست و بیتریت ممکن است در بعضی دقایق کمتر یا در بعضی دقایق بیشتر از این مقدار شود. | No |
bufferSize | string | سایز بافری که واحد عملیات کدک بر روی آن انجام میشود را مشخص میکند. (برحسب بایت) | No |
maxBitrate | string | در عملیات تبدیل در صورتی که maxBitrate را ست کرده باشید مقدار bitrate هیچ وقت از این عدد بالاتر نمیرود. این گزینه به درد مواقعی میخورد که میخواهید از جهشهای ناگهانی bitrate که ممکن است به وجود بیاید جلوگیری کنید. (مقدار دهی آن مانند مقدار دهی bitrate است) | No |
minBitrate | string | در عملیات تبدیل در صورتی که minBitrate را ست کرده باشید مقدار bitrate هیچ وقت از این عدد پایینتر نمیرود. (مقدار دهی آن مانند مقدار دهی bitrate است) | No |
توضیحات ۱: در نظر داشته باشید با توجه به این که سرویس VoD در حال حاضر حداکثر از resolution ورودی و خروجی 1080p پشتیبانی میکند، در صورتی که بخواهیم محدودیت عرض و ارتفاع تصویر را دقیقتر بیان کنیم، مقدار ماکسیمم عرض و ارتفاع تصویر حداکثر ۱۹۲۰ پیکسل میتواند باشد و مقدار مینیمم عرض و ارتفاع تصویر حداکثر ۱۰۸۰ پیکسل میتواند باشد. با این محدودیت ورودی و خروجیهای تا رزولوشن 1080p چه به صورت portrait چه landscape پشتیبانی میشوند.