استفاده از 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 را مطابق جدول زیر تعیین کنید. (رعایت کوچک و بزرگ بودن حروف مهم است):

FieldTypeValueMandatory
apiVersionstringdelivery.ravh.ir/v1Yes
kindstringTranscodeYes

metadata

در قسمت metadata.name می‌توانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید:

FieldTypeValueMandatory
namestringAccording to RFC 1123Yes
namespacestringAccording to RFC 1123No

spec

این قسمت به ۳ بخش input, output و pipelineName تقسیم می‌شود که در ادامه جزییات هر یک به تفضیل شرح داده شده است:

FieldTypeDescriptionMandatory
inputobjectتنظیمات s3 و فایل‌ ورودی برای تبدیلYes
outputobjectمشخصات خروجی تبدیل شدهYes
pipelineNamestringرفرنس به تعریف pipeline (مشخصات تبدیل)No
pipelineSpecobjectدر صورت تمایل، می‌توانید به جای ست کردن نام و اشاره‌گر به پایپ‌لاین از پیش‌ ساخته شده با استفاده از فیلد pipelineName، از این فیلد استفاده کنید و فیلدهای مربوط به pipeline را به صورت inline در manifest ترانسکد وارد کنید.No

توجه: فیلد‌های pipelineName و pipelineSpec هر کدام به تنهایی الزامی نمی‌باشند ولی حداقل یکی از این دو فیلد باید داخل transcode spec ست شده باشد. در صورتی که هیچ یک از این دو فیلد مقدار معتبر نداشته باشند، api ارور validation برمی‌گرداند.

spec.input

این قسمت شامل مشخصات فایل ورودی است که می‌خواهید عملیات Transcode بر روی آن‌ انجام شود. در نظر داشته باشید که عرض و ارتفاع ویدئو استریم مشخص شده در این قسمت از تنظیمات دارای محدودیت هستند. به این صورت که مقدار ماکسیمم عرض و ارتفاع ویدئو استریم ورودی از ۱۹۲۰ پیکسل باید کم‌تر باشد. همچنین، مقدار مینیمم عرض و ارتفاع ویدئو استریم ورودی از ۱۰۸۰ پیکسل باید کم‌تر باشد.

در حال حاضر فقط از یک نوع input پشتیبانی می‌شود، جزئیات این فیلد در ادامه شرح داده شده است:

FieldTypeDescriptionMandatory
protocolstringدر حال حاضر فقط s3 پشتیبانی می‌شودYes
s3objectمشخصات s3 endpoint و باکت و نام آبجکتYes
FieldTypeDescriptionMandatory
endpointobjectمشخصات s3 endpoint برای دریافت فایل ورودی Yes
bucketstringاسم باکتی که فایل داخل آن استYes
objectstringآدرس  یا prefix فایل داخل باکتYes
FieldTypeDescriptionMandatory
kisebooleanآیا فایل ورودی روی کیسه ذخیره شده است؟Yes
addressstringآدرس endpoint سرویس S3Yes
accessKeystringکلید دسترسی (در صورتی که ازs3 غیر از کیسه استفاده می‌کنید)No
secretKeystringکلید مخفی (‌در صورتی که از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 کلیدهای سرویس کاربر مورد نظر دسترسی داشته باشید.

FieldTypeDescriptionMandatory
workspaceIdstringمشخصه workspace که از طریق پنل اوشن و قسمت بپا قابل دسترسی می‌باشد.Yes
userIdstringشناسه‌ی service user که از طریق پنل اوشن و قسمت بپا قابل ساخت و دسترسی می‌باشد.Yes
prefixstringمسیر ذخیره فایل در باکت که میتواند به صورت x/y/z باشد. توجه کنید که در صورتی که مسیر تکراری برای دو ترانسکد وارد کنید، فایل‌های ترانسکد دوم، روی مسیر ترانسکد اول overwrite خواهند شد، در صورتی که این فیلد را پر نکرده باشید یک مقدار به صورت تصادفی ساخته خواهد شد.No

spec.pipelineName

هر ترانسکد نیاز به یک پایپلاین برای تعریف خروجی‌های مختلف، کیفیت‌ها، پلی‌لیست‌ها و thumbnail‌ها دارد. که رفرنس این pipeline در این فیلد ذخیره خواهد شد. به عبارتی دیگر اگر مقدار این فیلد x باشد حتما باید یک pipeline با نام x در namespace شما وجود داشته باشد.

توجه: چنانچه مایل باشید می‌توانید به جای استفاده از pipelineName از pipelineSpec استفاده کنید. و

فیلدهای مربوط به pipeline را به صورت inline در manifest ترانسکد وارد کنید.

:Status

بیانگر آخرین وضعیت یک transcode ساخته شده است که در واقع یک آبجکت است. در ادامه به فیلدهای این آبجکت اشاره می‌کنیم:

DescriptionTypeField
این فیلد نمایش دهنده‌ی آخرین وضعیت transcode مورد نظر است. حالت‌های مختلف این وضعیت در جدول بعد آورده شده است.stringstate
این فیلد نمایش دهنده‌ی میزان پیشرفت transcode استریم‌های ورودی به صورت درصدی است.stringprogress
این فیلد نمایش‌دهنده‌ی سرعت فرایند transcode استریم‌های ورودی می‌باشد که در واقع نسبت طول زمانی استریم‌های ورودی به میزان زمان طی شده برای انجام فرایند transcode است.stringspeed
این فیلد نمایش‌دهنده‌ی اسم bucketای است که خروجی‌های transcode در آن قرار گرفته‌اند. stringoutputBucket
مقدار این فیلد prefix همه‌ی آبجکت‌های آپلود شده در باکت خروجی است.stringoutputPrefix
در صورتی که وضعیت transcode مورد نظر در حالت Failed باشد و در واقع این فرایند fail شده باشد، این فیلد جهت نمایش علت و توضیحات بیشتر در موردش ارور پیش‌آمده است.در صورتی که transcode با موفقیت انجام شده باشد، این فیلد شامل آدرس cdn سرو خروجی‌های transcode است.stringmessage
DescriptionState
این وضعیت که حالت اولیه‌ی 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 را مطابق جدول زیر تعیین کنید. (رعایت کوچک و بزرگ بودن حروف مهم است):

FieldTypeValueMandatory
apiVersionstringdelivery.ravh.ir/v1Yes
kindstringTranscodeYes

metadata

در قسمت metadata.name می‌توانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید:

FieldTypeValueMandatory
namestringAccording to RFC 1123Yes
namespacestringAccording to RFC 1123No

spec

این قسمت به ۳ بخش playlist, outputs و thumbs تقسیم می‌شود که در ادامه جزییات هر یک به تفضیل شرح داده شده است:

FieldTypeDescriptionMandatory
outputs[]objectلیست خروجی‌ها (کیفیت صدا و تصویر)Yes
playlistobjectدر صورت درخواست ایجاد playlist از فایل‌های خروجی باید این قسمت پیکربندی شودNo
thumbsobjectدر صورت درخواست تولید فایل‌های thumbnail با فاصله‌های زمانی مشخص، از فایل‌های خروجی این قسمت باید پیکربندی شودNo

spec.outputs

در قسمت spec.outputs، ما لیستی از output های مختلفی را که می‌خواهیم تولید شود، تعریف می‌کنیم. برای این کار از تنظیمات زیر به ازای هر output استفاده می‌کنیم.

FieldTypeDescriptionMandatory
keystring (unique in list)یک نام یکتا که به این تعریف خروجی نسبت می‌دهیدYes
presetNamestringنام آبجکت Preset ای که تعریف صوت و تصویر این خروجی از روی آن خوانده می‌شود. در ادامه نحوه تعریف یک Preset توضیح داده خواهد شد.No
excludeFromPlaylistboolدر صورتی که می‌خواهید این خروجی به playlist اضافه نشود، این گزینه را true کنیدNo
excludeFromThumbsboolدر صورتی که می‌خواهید برای این خروجی thumbs ساخته نشود، این گزینه را true کنیدNo
presetSpecobjectدر صورت تمایل، می‌توانید به جای ست کردن presetName، از این فیلد استفاده کنید و فیلدهای مربوط به preset را به صورت inline در manifest پایپ‌لاین وارد کنید.No

توجه: فیلد‌های presetName و presetSpec هر کدام به تنهایی الزامی نمی‌باشند ولی حداقل یکی از این دو فیلد باید داخل pipeline spec ست شده باشد. در صورتی که هیچ یک از این دو فیلد مقدار معتبر نداشته باشند api ارور validation برمی‌گرداند.

spec.playlist

پلی‌لیست یک پروتکل استریم‌ انطباقی است که قابلیت پخش یک فایل چندرسانه‌ای را بر بستر http فراهم می‌کند از معروفترین این پروتکل‌ها می‌توان به HLS و DASH اشاره کرد. در ادامه فیلدهای مربوط به قسمت playlist شرح داده می‌شوند:

FieldTypeDescriptionMandatory
enabledboolآیا این playlist فعال است یا خیرYes
namestringنامی که می‌خواهید playlist تان داشته باشدYes
formatstringفرمت playlist در حال حاضر فقط hls پشتیبانی می‌شودYes
hlsobjectپیکربندی hlsYes
spec.playlist.hls
FieldTypeDescriptionMandatory
segmentDurationintزمان تقریبی هر سگمنت را مشخص می‌کندYes

spec.thumbs

تصویر بندانگشتی (Thumbnail) به تصاویر کوچکی گفته می‌شود که از روی یک تصویر اصلی یا فریمی از یک ویدیو ایجاد می‌شود و معمولا به کاربر در یافتن محتوای تصویری مورد نظر خود در میان انبوهی از تصاویر و ویدیوها کمک می‌کند.

FieldTypeDescriptionMandatory
formatstringفرمت تصاویر می‌تواند jpg یا png باشدYes
intervaluintزمان بین عکس‌ها به ثانیهYes

یک Preset بیانگر کیفیت صدا و تصویر یک خروجی مشخص شده در پایپلاین است. اینکه codec صوت و تصویر، frameRate و bitrate و سایر تنظیمات چه باشد. اینجا هم برای راحتی کار و تسریع ایجاد Job می‌توانید Presetهایی از قبل تعریف کنید و در تعریف Pipeline از آن استفاده کنید.

در ادامه نمونه‌ای از manifest یک preset را مشاهده می‌کنید:

مقادیر apiVersion و kind را مطابق جدول زیر تعیین کنید. (رعایت کوچک و بزرگ بودن حروف مهم است):

FieldTypeValueMandatory
apiVersionstringdelivery.ravh.ir/v1Yes
kindstringTranscodeYes

metadata

در قسمت metadata.name می‌توانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید:

FieldTypeValueMandatory
namestringAccording to RFC 1123Yes
namespacestringAccording to RFC 1123No
FieldTypeDescriptionMandatory
descriptionstringتوضیح دلخواه در مورد این پیکربندیNo
containerstringفرمت فایل نهایی تولیدی، می‌تواند یکی از مقادیر mp4، m4v، mov و یا avi باشد.Yes
speedstringسرعت تبدیل، می‌تواند medium، veryfast و ultrafast باشد. مقدار توصیه‌ شده استفاده از veryfast است که هم سرعت و هم کیفیت خوبی در خروجی دارد.No
skipAudioboolدر صورتی که می‌خواهید کانال صدا از خروجی حذف شود این فیلد را true کنید.Yes
skipVideoboolدر صورتی که می‌خواهید کانال‌های تصویر از خروجی حذف شود این فیلد را true کنید. توجه کنید که هر دو فیلد skipAudio و skipVideo نمی‌توانند همزمان true باشند.Yes
audioobjectتنظیمات صداYes
videoobjectتنظیمات تصویرYes
FieldTypeDescriptionMandatory
codecstringنوع کدک صدا را مشخص می‌کند. می‌تواند یکی از مقادیرaac, mp3, vorbis, opus, copy باشد. مقدار copy به معنای کپی کردن کدک ورودی در خروجی بدون تغییر استYes
bitratestringنرخ استریم صدا را مشخص می‌کند. می‌توان مقادیری چون 100، 1k، و 1m به آن نسبت داد. در یک کدک ثابت بیت‌ریت بالاتر به معنی کیفیت بالاتر است No
sampleRateuintنرخ نمونه‌برداری از صدای ورودی برای تولید صدای خروجی است و می‌تواند یکی از مقادیر زیر باشد22050 ,32000 ,44100 ,48000 ,96000No
FieldTypeDescriptionMandatory
codecstringنوع کدک تصویر را مشخص می‌کند. می‌تواند یکی از مقادیر h264،h265 و یا vp9 باشد.Yes
resizeTypestringاین فیلد روش تغییر طول و عرض تصویر را مشخص می‌کند و میتواند یکی از مقادیر unconstrained یا percentage یا autoWidth و یا autoHeight باشد که در ادامه هریک توضیح داده شده: :unconstrained محدودیتی در تعیین اندازه طول و عرض تصویر نبوده و میتوانید مقدار دلخواه را برای طول و عرض تصویر مشخص کنید:percentage نسبت طول و عرض تصویر حفظ شده و به میزانی که در فیلد percentage گفته شده تصویر بزرگ یا کوچک می‌شود.:autoWidthنسبت تصویر حفظ می‌شود اما مقدار height گرفته می‌شود و بر مبنای آن width تغییر می‌کند.autoHeightنسبت تصویر حفظ می‌شود اما مقدار width گرفته می‌شود و بر مبنای آن height تغییر می‌کند.Yes
widthuintعرض تصویر به پیکسل. حداکثر اندازه‌ی عرض تصویر ۱۹۲۰ پیکسل می‌باشد. (لطفا توضیحات شماره ۱ مطالعه شود.)No
heightuintارتفاع تصویر به پیکسل. حداکثر اندازه‌ی ارتفاع تصویر ۱۹۲۰ پیکسل می‌باشد. (لطفا توضیحات شماره ۱ مطالعه شود.)No
percentageuintدرصد بزرگنمایی در حالتی که resizeType روی حالت percentage تنظیم شده باشد. حداکثر 1000No
frameRateuintنرخ تصویر در ثانیه، حداکثر 120No
bitratestringنرخ متوسط استریم تصویر را مشخص می‌کند. مقدار این فیلد می‌تواند یک عدد بدون واحد (مثلا 120) یا عدد همراه با واحد باشد (1m یا 2k) که m به معنای میلیون و k به معنای هزار است. در یک کدک ثابت، بیت‌ریت بالاتر به معنی کیفیت بالاتر است. این مقدار لزوما بیت‌ریت خروجی نیست و بیت‌ریت ممکن است در بعضی دقایق کمتر یا در بعضی دقایق بیشتر از این مقدار شود.No
bufferSizestringسایز بافری که واحد عملیات کدک بر روی آن انجام می‌شود را مشخص می‌کند. (برحسب بایت)No
maxBitratestringدر عملیات تبدیل در صورتی که maxBitrate را ست کرده باشید مقدار bitrate هیچ وقت از این عدد بالاتر نمی‌رود. این گزینه به درد مواقعی می‌خورد که می‌خواهید از جهش‌های ناگهانی bitrate که ممکن است به وجود بیاید جلوگیری کنید. (مقدار دهی آن مانند مقدار دهی bitrate است)No
minBitratestringدر عملیات تبدیل در صورتی که minBitrate را ست کرده باشید مقدار bitrate هیچ وقت از این عدد پایین‌تر نمی‌رود. (مقدار دهی آن مانند مقدار دهی bitrate است)No

توضیحات ۱: در نظر داشته باشید با توجه به این که سرویس VoD در حال حاضر حداکثر از resolution ورودی و خروجی 1080p پشتیبانی می‌کند، در صورتی که بخواهیم محدودیت عرض و ارتفاع تصویر را دقیق‌تر بیان کنیم، مقدار ماکسیمم عرض و ارتفاع تصویر حداکثر ۱۹۲۰ پیکسل می‌تواند باشد و مقدار مینیمم عرض و ارتفاع تصویر حداکثر ۱۰۸۰ پیکسل می‌تواند باشد. با این محدودیت ورودی و خروجی‌های تا رزولوشن 1080p چه به صورت portrait چه landscape پشتیبانی می‌شوند.

آیا این مقاله به شما کمک کرد؟

با نظر دادن به بهبود کیفیت مستندات کمک کنید

sotoon

کلیه حقوق مادی و معنوی محفوظ است. © ۱۴۰۳ ستون/ شرکت رایانش ابری واحد هزاردستان