ویدیو ترسنکودینگ - REST

نکته: در صورتی که با مفهوم REST و سرویس‌های سمت سرور و یا با دستور curl آشنایی ندارید، به آشنایی با REST مراجعه کنید.

پیش‌نیازها

  1. در صورتی که با سرویس فایل آشنایی ندارید، به معرفی سرویس فایل مراجعه کنید.
  2. در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای سرویس فایل خود را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
  3. در صورتی که با درخواست Multipart آشنایی ندارید، به درخواست Multipart مراجعه کنید.
  4. در صورتی که با راه‌اندازی کتابخانه REST در پلتفرم خود آشنایی ندارید، به راه‌اندازی کتابخانه‌های REST مراجعه کنید.
  5. در صورتی که با سرویس کاربران بکتوری آشنایی ندارید، به معرفی سرویس کاربران مراجعه کنید.

مقدمه

در این مستند قرار است به خدمات مختلفی که بکتوری در زمنیه ویدیو اراعه می‌دهد بپردازیم. در ابتدا کمی درباره مفاهیم کلی و خدمات رایج این حوزه توضیح می‌دهیم.

VOD

ویدئو به‌درخواست (VOD یا Video on Demand) سیستم‌هایی هستند که به کاربران اجازه می‌دهند محتواهای صوتی یا تصویری را هر زمان که خودشان خواستند گوش/تماشا کنند. در این سیستم کاربران مجبور نیستند برنامه‌ها را در زمان پخش سراسری تماشا کنند. فناوری IPTV اغلب به همین منظور و برای اینکه VOD را به تلویزیون‌ها و کامپیوترهای شخصی بیاورد مورد استفاده قرار می‌گیرد.

سیستم‌های VOD تلویزیونی می‌توانند محتویات را از طریق یک ستاپ باکس، یک کامپیوتر یا دستگاه‌های دیگر استریم (stream) کرده و به کاربر این اجازه را می‌دهد تا به صورت آنی محتویات را تماشا کند یا آن‌ها را روی کامپیوتر، دستگاه‌های ضبط دیجیتال ویدئو (که دستگاه شخصی ضبط ویدئو نیز نامیده می‌شوند) یا پخش‌کننده‌های قابل‌حمل دانلود کند تا هر زمان که تمایل داشت، آن را تماشا کند. اغلب ارائه‌دهندگان تلویزیون کابلی یا مخابراتی، استریم VOD را به کاربران عرضه می‌کنند که هم شامل محتویات رایگان و هم محتویات pay-per-view (پرداخت به ازای تماشا) می‌باشد. در این سرویس کاربر یک فیلم یا برنامه تلویزیونی را انتخاب و خریداری می‌کند و برنامهٔ مورد نظر همان لحظه روی تلویزیون کاربر پخش می‌شود. حتی کاربر می‌تواند آن را روی یک دستگاه ضبط ویدئو ذخیره، یا روی کامپیوتر شخصی‌اش دانلود کرده و در زمان دلخواه تماشا کند. تلویزیون اینترنتی که از اینترنت استفاده می‌کند یکی از انواع VOD است که علاقه‌مندان زیادی پیدا کرده است.

HLS

HLS یا Http Live Streaming یک پروتوکل انتقال مدیا بر پایه Http می‌باشد. کارکرد آن به این صورت می‌باشد که کل استریم را به چندین دانلود فایل مبتنی بر Http می‌شکند، که هر دانلود قسمت کوچکی از کل استریم می‌باشد. هنگام پخش کلاینت می‌تواند بین تعدادی استریم حاوی محتوای یکسان ولی نرخ‌های مختلف انتخاب کند و از این طریق فرایند استریم را با نرخ موجود هماهنگ کند.

در ابتدای فرایند استریم، HLS یک پلی‌لیست M3U حاوی متادیتای استریم‌های موجود دانلود می‌کند تا از طریق آن استریم مطلوبش را انتخاب کند. ازآنجایی که درخواست‌ها مبتنی بر Http می‌باشد HLS می‌تواند از هر Fire Wall یا Proxy Server که درخواست‌های ‌ Http را قبول می‌کند عبور کند، که این مزیت آن نسبت به سایر پروتوکل‌ها برای کار مشابه می‌باشد. این قابلیت HLS همچنین امکان اراعه محتوا روی شبکه‌های CDN مبتنی بر Http را نیز فراهم می‌آورد.

HLS همچنین قابلیت استفاده از مکانیزم‌های رمزنگاری مختلفی را نیز دارا است.

ABS

Bit Rate برابر است با تعداد بیت‌هایی که میتوان در واحد زمان انتقال داد. معمولا بر حسب بیت بر ثانیه اندازه‌گیری می‌شود.

Adaptive Bitrate Streaming یا ABS یک تکنیک مدیریت کارایی برای استریم محتوای چند رسانه‌ای بر روی شبکه‌های کامپیوتری است. نحوه کار آن این گونه است که به صورت پویا CPU و ‌Memory را کنترل می‌کند و مطابق آن تصمیم مناسب را برای کیفیت ویدیو می‌گیرد. این فرایند ملزم این است که ویدیوی اصلی به بیت ریت‌های مختلف encode شود و سپس به قسمت‌های ریز شکسته شود، که طول هر قسمت معمولا بین ۲ تا ۱۰ ثانیه می‌باشد. اگر پخش‌کننده کاربر قابلیتش را داشته‌ باشد می‌تواند از ABS استفاده کند، یعنی باید بتواند بین قسمت‌ها با بیت ریت متفاوت جابه‌جا شود و مناسب ترین آن‌ها را انتخاب کند.

لیست قسمت‌های ویدیو و بیت ریت‌های آن‌ها در یک فایل منیفست نوشته شده‌اند که در ابتدای کار در اختیار کلاینت قرار می‌گیرد. سپس کلایت اولین قسمت را با کمترین بیت ریت آن درخواست می‌دهد و در صورتی که سرعت دانلود از بیت ریت مشخص شده بیشتر باشد بیت ریت بالاتر را درخواست می‌دهد و این روند را ادامه می‌دهد تا یک تطابق نزدیک پیدا کند سپس پخش را شروع می‌کند، و در ادامه اگر پهنای باند کاربر تغییر کند، بیت ریت مناسب درخواست داده می‌شود.

سرویس Transcoder بکتوری در حال حاضر قابلیت‌های زیر را ارائه می‌دهد:

نکته: یک فرآیند Convert بر اساس نیاز شما ممکن است به چندین بخش تقسیم شود که باید تنظیمات آن بخش را قبل از ارسال درخواست Convert انجام دهید. به عنوان مثال ممکن است فقط بخواهید از ویدیو ارسالی چند تصویر (Screen Shot) تهیه کنید یا لوگو خود را به ویدیو الحاق کنید (Watermark)، پس باید قبل از ارسال ویدیوی خود، ابتدا تنظیمات مربوط به Watermark و … را انجام دهید.

استفاده از سرویس‌ها

جهت استفاده از این سرویس‌ها باید مراحل زیر را طی نمایید:

  1. ابتدا برای بخش های مختلف convert باید تنظیمات لازم را ایجاد کنید. این بخش ها شامل thumbnail, watermark, webhook, upload, preset می‌باشد که تنظیمات هر بخش را در قسمت های بعدی توضیح می‌دهیم

  2. پس از مرحله بالا آدرس فایل مورد نظر خود را همراه با تنظیماتی که در مرحله قبل ایجاد کرده‌اید برای convert ارسال نمایید.

نکته: پس از اتمام convert فایل‌های خروجی به آدرسی که مشخص نموده‌اید ارسال می‌شود (در قسمت متادیتا، بخش upload)

تنظیمات یا متادیتا

شما می‌توانید برای قسمت‌های مختلف فرآیند convert، تنظیمات شخصی خودتان را اعمال کنید. به عنوان مثال می‌توانید تنظیم کنید که لوگوی محصول خودتان بر روی ویدیو چسبانده شود و یا اینکه از ویدیو تصویرهایی در زمان‌های مختلف بگیرید؛ و در آخر آدرسی که باید نتایج convert آپلود شود را مشخص نمایید.

تمام قسمت‌های قابل تنظیم که در ادامه توضیح داده می‌شوند شامل فیلد name و default بوده، که توسط این فیلدها می‌توانید تنظیمات متفاوت با نام‌های مختلف برای هر قسمت داشته باشید و همچنین می‌توان یکی از آن‌ها را به عنوان پیش فرض مشخص نمایید.

Thumbnail

در حال حاضر به سه حالت thumbnail می‌توانید تهیه کنید:

  1. مشخص کردن زمان های thumbnail به صورت دستی

  2. به صورت تصادفی

  3. thumbnail در بازه های زمانی منظم

تنظیمات مربوط به این بخش برای گرفتن تصویر یا به اصطلاح thumbnail کاربرد دارد و در صورت نیاز می‌توانید از آن استفاده نمایید.

نکته:اولویت در نظر گرفتن فیلدها نیز به ترتیب برابر shot سپس random و interval می‌باشد.

نمونه درخواست:

curl -X POST \
  http://transcoder.api.backtory.com/metadata/thumbnail \
  -H 'authorization: bearer <Access-Token>' \
  -H 'content-type: application/json' \
  -d '{
	"name": "app1RandomThumbnail",
    "default": true,
    "shots": [
		"00:24:15",
		"00:40:42",
		"01:15:54"
	],
	"count": 5,
    "random": false,
	"interval": 5,
	"startTime": 5
        }'

در مثال بالا چون اولویت shots بیشتر می‌باشد لذا نوع thumbnail دستی در نظر گرفته می‌شود و مابقی حالت‌ها انجام نمی‌شود و فقط سه عدد thumbnail در زمان‌های مشخص شده گرفته می‌شود.

Webhook

شما می‌توانید یک url مشخص نموده و اطلاعات مربوط به وضعیت ویدیوهای ارسالی خود را از طریق url معرفی شده دریافت نمایید.

داده های ارسالی به url شما یک JSON به صورت زیر می‌باشد:

{
    “queueId”: “{QUEUE_ID}”,
    “requestId”: “{REQUEST_ID}”,
    “status”: “{REJECTED | THUMBNAIL_REJECTED | COMPLETE}”,
    “job”: “{convert | thumbnail}”,
    “payload”: {},
    “retry”: “0”
}

نمونه‌ای از این درخواست به صورت زیر می‌باشد:

curl -X POST \
  http://transcoder.api.backtory.com/metadata/webhook \
  -H 'authorization: bearer <Access-Token>' \
  -H 'content-type: application/json' \
  -d '{
	"name": "test_webhook",
	"url": "http://example.com/webhook.php"
}'

Upload

پس از اتمام مرحله convert فایل‌های تبدیل شده به آدرسی که در این قسمت مشخص می‌کنید آپلود می‌شوند.

نمونه‌ای از این درخواست به صورت زیر می‌باشد:

curl -X POST \
  http://transcoder.api.backtory.com/metadata/upload \
  -H 'authorization: bearer <Access-Token>' \
  -H 'content-type: application/json' \
  -d '{
	"name": "backtory",
	"url": "http://storage.backtory.com/upload",
	"headers": {
		"authorization": "bearer <Access-Token>",
		"test_header": "test value"
	}
}'

نتایج عملیات در قالب پنج دسته برای شما ارسال می‌شود:

1. Thumbnail

2. فایل های تبدیل شده (بدون VOD)

3. چانک فایل ها (در حالت VOD)

4. فایل playlist (در حالت VOD)

5. فایل های قابل دانلود vod (در حالت VOD)

نکته: در حال حاضر VOD فقط HLS پشتیبانی می‌شود و همانطور که اطلاع دارید فایل‌های HLS را به صورت عادی نمی‌توان دانلود نمود و برای اینکار نیاز به ابزارهای خاصی دارید لذا شما برای دانلود فایل‌ها توسط کاربران باید از هر کیفیت یک نسخه نیز مخصوص دانلود داشته باشید. منظور از فایل های قابل دانلود VOD همین فایل‌ها می‌باشد. جهت تولید کردن این فایل‌ها نیز در بخش‌های جلوتر نحوه ساختن آن‌ها را توضیح خواهیم داد (بخش preset).

نکته: در حالت VOD چون نیاز داریم داخل فایل playlist.m3u8 آدرس فایل‌های کیفیت‌های مختلف را بدهیم، لذا این موضوع ضرورت پیدا می‌کند که فایل‌های ویدیوهایی را که به حالت VOD تبدیل شده‌اند، درست در محلی که به وسیله request آپلود گفته می‌شود قرار داده باشید، تا توسط آدرس هایی که در فایل playlist.m3u8 ذکر شده است قابل دسترسی باشند.

{
    “requestId”: “{REQUEST_ID}”,
    “videoId”: “{VIDEO_ID}”,
    “thumbnail”: true,
    “file”: “THUMBNAIL_FILE”
}

{
    “requestId”: “{REQUEST_ID}”,
    “videoId”: “{VIDEO_ID}”,
    “vod”: false,
    “file”: “CONVERTED_FILE”
}

{
    “requestId”: “{REQUEST_ID}”,
    “videoId”: “{VIDEO_ID}”,
    “vod”: true,
    “resolution”: “720”,
    “path”:  “{UPLOAD_PATH}”
    “file”: “HLS_CHUNK_FILE”
}

نکته: همانطور که قبلا نیز ذکر شده‌است، قطعات کوچک تر HLS باید درست در مسیری که در فایل playlist.m3u8 اصلی گفته شده است قرار گیرند. لذا همراه request هایی که فیلد vod آنها true می‌باشد دارای دو فیلد اضافه‌تر به نام‌های path و resolution هستند. فیلد path حاوی مسیری است که باید فایل شما در آن محل قرارگیرد. فیلد resolution نیز حاوی ارتفاع کیفیت فعلی است که در صورت نیاز می‌توانید از آن استفاده نمایید.

{
    “requestId”: “{REQUEST_ID}”,
    “videoId”: “{VIDEO_ID}”,
    “vod”: true,
    “playlist”: true,
    “path”:  “{UPLOAD_PATH}”
    “file”: “HLS_PLAYLIST_FILE”
}

{
    “requestId”: “{REQUEST_ID}”,
    “videoId”: “{VIDEO_ID}”,
    “vod”: true,
    “downloadable”: true,
    “file”: “DOWNLOADABLE_FILE”
}

فایل های HLS را به صورت زیر می‌توانید ذخیره کنید:

-----/playlist.m3u8  ------> playlist حاوی ABS
-----/144/playlist.m3u8
-----/240/playlist.m3u8
-----/360/playlist.m3u8
-----/480/playlist.m3u8

WaterMark

می‌توان یک عکس را به عنوان لوگو به ویدیو چسباند. در حال حاضر فقط watermark ثابت پشتیبانی می‌شود و در آینده watermark متحرک نیز اضافه خواهد‌شد.

نمونه‌ای از این درخواست به صورت زیر می‌باشد:

curl -X POST \
  http://transcoder.api.backtory.com/metadata/watermark \
  -H 'authorization: bearer <Access-Token>' \
  -H 'content-type: application/json' \
  -d '{
	"location": "left_top",
	"paddingY": 20,
	"paddingX": 30,
	"name": "watermark",
	"url": "http://example.com/logo.jpg",
	"default": true
}'

Preset

این قسمت شامل تنظیمات convert می‌باشد و می‌توانید تنظیمات مختلفی را اعمال نمایید.

به عنوان مثال شما یک ویدیو را به فرمت HLS و سایز های 240 و 360 تبدیل نموده‌اید و خروجی باید برای شما ارسال شود. در این حالت یک فایل playlist.m3u8 کلی خواهید داشت که حاوی مقادیر زیر می‌باشد:

#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=296000
http:/storage.backtory.com/test/vod/hls/2018-12-12/d548-s859.mp4/360/playlist.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1, BANDWIDTH=139000
http:/storage.backtory.com/test/vod/hls/2018-12-12/d548-s859.mp4/240/playlist.m3u8

آدرس های داده شده شامل دو قسمت می‌باشد:

http:/storage.backtory.com/test/vod/hls/2018-12-12/d548-s859.mp4/360/playlist.m3u8

  1. <http:/storage.backtory.com/test>

  2. /vod/hls/2018-12-12/d548-s859.mp4/360/playlist.m3u8

قسمت اول آدرسی می‌باشد که توسط فیلد path در request آپلود برای شما ارسال می‌شود و باید فایل را در همین آدرس بر روی سرور خود قرار دهید قسمت دوم آدرسی می‌باشد که توسط فیلد vodPlaylistBaseUrl مشخص نموده‌اید.

نمونه‌ای از این درخواست به صورت زیر می‌باشد:

curl -X POST \
  http://transcoder.api.backtory.com/metadata/preset \
  -H 'authorization: bearer <Access-Token>' \
  -H 'content-type: application/json' \
  -d '{
	"vod": false,
	"name": "convert_test",
	"speed": "medium",
	"default": true,
	"videoEncoder": "x264",
	"audioEncoder": "aac",
	"profile": "main",
	"outputs": [
		{
			"videoBitrate": "800",
			"audioBitrate": "128",
			"resolution": "897x480"
		},
		{
			"videoBitrate": "1500",
			"audioBitrate": "320",
			"resolution": "720"
		}
	],
	"encrypt": false,
	"vodPlaylistBaseUrl": "http://google.com/hls",
	"rawParameters": {
		"r": "2"	
	}
}'

ارسال ویدیو جهت Convert

پس از ذخیره کردن تنظیمات مورد نیاز خود می‌توانید فایلی را جهت تبدیل به سرویس ارسال نمایید و خروجی را دریافت کنید. شما می‌توانید درخواست خود را به صورت زیر ارسال نمایید:

نمونه‌ای از این درخواست به صورت زیر می‌باشد:

curl -X POST \
  http://transcoder.api.backtory.com/video/convert \
  -H 'authorization: bearer <Access-Token>' \
  -H 'content-type: application/json' \
  -d '{
           "url": "https://storage.backtory.com/test/test.mp4",
	"preset": "hls_convert_with_encrypt",
	"upload": "backtory_storage",
	"webhook": "backtory_webhook",
	"thumbnail": true,
	"watermark": "backtory_logo"
}'