IFrame player API به شما امکان می دهد یک پخش کننده ویدیوی YouTube را در وب سایت خود جاسازی کنید و پخش کننده را با استفاده از جاوا اسکریپت کنترل کنید.
با استفاده از توابع جاوا اسکریپت API، می توانید ویدیوها را برای پخش در صف قرار دهید. پخش، مکث یا توقف آن ویدیوها؛ تنظیم صدای پخش کننده؛ یا اطلاعات مربوط به ویدیوی در حال پخش را بازیابی کنید. همچنین میتوانید شنوندههای رویدادی را اضافه کنید که در پاسخ به رویدادهای پخش کننده خاص، مانند تغییر وضعیت پخش، اجرا میشوند.
این راهنما نحوه استفاده از IFrame API را توضیح می دهد. انواع مختلف رویدادهایی را که API میتواند ارسال کند را شناسایی میکند و نحوه نوشتن شنوندگان رویداد برای پاسخ به آن رویدادها را توضیح میدهد. همچنین توابع مختلف جاوا اسکریپت را که میتوانید برای کنترل پخشکننده ویدیو فراخوانی کنید و همچنین پارامترهای پخشکنندهای را که میتوانید برای سفارشیسازی بیشتر پخشکننده استفاده کنید، توضیح میدهد.
مرورگر کاربر باید از ویژگی postMessage
HTML5 پشتیبانی کند. اکثر مرورگرهای مدرن از postMessage
پشتیبانی می کنند.
Embedded players must have a viewport that is at least 200px by 200px. If the player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.
هر صفحه وب که از API IFrame استفاده می کند باید تابع جاوا اسکریپت زیر را نیز پیاده سازی کند:
onYouTubeIframeAPIReady
– وقتی صفحه دانلود جاوا اسکریپت برای API پخش کننده تمام شد، API این تابع را فراخوانی می کند، که به شما امکان می دهد سپس از API در صفحه خود استفاده کنید. بنابراین، این تابع ممکن است اشیاء پخش کننده ای را ایجاد کند که می خواهید هنگام بارگیری صفحه نمایش دهید.
صفحه نمونه HTML زیر یک پخش کننده تعبیه شده ایجاد می کند که یک ویدیو را بارگیری می کند، آن را به مدت شش ثانیه پخش می کند و سپس پخش را متوقف می کند. نظرات شماره گذاری شده در HTML در لیست زیر مثال توضیح داده شده است.
<!DOCTYPE html> <html> <body> <!-- 1. The <iframe> (and video player) will replace this <div> tag. --> <div id="player"></div> <script> // 2. This code loads the IFrame Player API code asynchronously. var tag = document.createElement('script'); tag.src = "https://www.youtube.com/iframe_api"; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); // 3. This function creates an <iframe> (and YouTube player) // after the API code downloads. var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } // 4. The API will call this function when the video player is ready. function onPlayerReady(event) { event.target.playVideo(); } // 5. The API calls this function when the player's state changes. // The function indicates that when playing a video (state=1), // the player should play for six seconds and then stop. var done = false; function onPlayerStateChange(event) { if (event.data == YT.PlayerState.PLAYING && !done) { setTimeout(stopVideo, 6000); done = true; } } function stopVideo() { player.stopVideo(); } </script> </body> </html>
لیست زیر جزئیات بیشتری در مورد نمونه بالا ارائه می دهد:
تگ
<div>
در این بخش مکانی را در صفحه ای که API IFrame پخش کننده ویدیو را در آن قرار می دهد، مشخص می کند. سازنده شی پخش کننده، که در بخش Loading a video player توضیح داده شده است، تگ<div>
را باid
خود شناسایی می کند تا مطمئن شود که API<iframe>
را در مکان مناسب قرار می دهد. به طور خاص، IFrame API تگ<div>
را با تگ<iframe>
جایگزین می کند.به عنوان جایگزین، میتوانید عنصر
<iframe>
را مستقیماً در صفحه قرار دهید. بخش Loading a video player نحوه انجام این کار را توضیح می دهد.کد موجود در این بخش کد جاوا اسکریپت API IFrame Player را بارگیری می کند. مثال از اصلاح DOM برای دانلود کد API استفاده می کند تا اطمینان حاصل شود که کد به صورت ناهمزمان بازیابی می شود. (ویژگی
async
تگ<script>
، که دانلودهای ناهمزمان را نیز فعال می کند، هنوز در همه مرورگرهای مدرن پشتیبانی نمی شود، همانطور که در این پاسخ Stack Overflow بحث شد.عملکرد
onYouTubeIframeAPIReady
به محض دانلود کد API پخش کننده اجرا می شود. این بخش از کد یک متغیر سراسری،player
تعریف می کند، که به پخش کننده ویدیویی که در حال تعبیه آن هستید اشاره دارد و سپس تابع، شی پخش کننده ویدیو را می سازد.تابع
onPlayerReady
زمانی اجرا می شود که رویدادonReady
فعال شود. در این مثال، عملکرد نشان می دهد که وقتی پخش کننده ویدیو آماده است، باید شروع به پخش کند.API تابع
onPlayerStateChange
را هنگامی که وضعیت بازیکن تغییر میکند، فراخوانی میکند، که ممکن است نشاندهنده این باشد که پخشکننده در حال بازی کردن، توقف، تمام شدن و غیره است. این عملکرد نشان می دهد که وقتی وضعیت پخش1
است (در حال پخش)، پخش کننده باید به مدت شش ثانیه پخش شود و سپس تابعstopVideo
را فراخوانی کند تا ویدیو متوقف شود.
پس از بارگیری کد جاوا اسکریپت API، API تابع onYouTubeIframeAPIReady
را فراخوانی می کند، در این مرحله می توانید یک شی YT.Player
برای درج یک پخش کننده ویدیو در صفحه خود بسازید. گزیده HTML زیر تابع onYouTubeIframeAPIReady
را از مثال بالا نشان می دهد:
var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); }
سازنده برای پخش کننده ویدیو پارامترهای زیر را مشخص می کند:
پارامتر اول یا عنصر DOM یا
id
عنصر HTML را مشخص می کند که در آن API تگ<iframe>
حاوی پخش کننده را درج می کند.IFrame API عنصر مشخص شده را با عنصر
<iframe>
حاوی پخش کننده جایگزین می کند. اگر عنصری که جایگزین می شود سبک نمایش متفاوتی نسبت به عنصر درج شده<iframe>
داشته باشد، می تواند روی طرح بندی صفحه شما تأثیر بگذارد. به طور پیشفرض، یک<iframe>
به عنوان یک عنصرinline-block
نمایش داده میشود.- پارامتر دوم یک شی است که گزینه های پخش کننده را مشخص می کند. شی شامل ویژگی های زیر است:
-
width
(عدد) - عرض پخش کننده ویدیو. مقدار پیش فرض640
است. -
height
(تعداد) - ارتفاع پخش کننده ویدیو. مقدار پیش فرض390
است. -
videoId
(رشته) - شناسه ویدیوی YouTube که ویدیویی را که پخش کننده بارگذاری می کند، مشخص می کند. -
playerVars
(شیء) - ویژگی های شیء پارامترهای پخش کننده را شناسایی می کند که می توان از آنها برای سفارشی کردن پخش کننده استفاده کرد. -
events
(شیء) - ویژگی های شیء رویدادهایی را که API اجرا می کند و توابع (شنونده های رویداد) را که API هنگام وقوع آن رویدادها فراخوانی می کند، مشخص می کند. در مثال، سازنده نشان میدهد که تابعonPlayerReady
زمانی اجرا میشود که رویدادonReady
فعال میشود و تابعonPlayerStateChange
زمانی که رویدادonStateChange
فعال میشود، اجرا میشود.
-
همانطور که در بخش شروع به کار ذکر شد، به جای نوشتن یک عنصر خالی <div>
در صفحه خود، که کد جاوا اسکریپت API پخش کننده با عنصر <iframe>
جایگزین می شود، می توانید تگ <iframe>
را خودتان ایجاد کنید. اولین مثال در بخش Examples نحوه انجام این کار را نشان می دهد.
<iframe id="player" type="text/html" width="640" height="390" src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com" frameborder="0"></iframe>
توجه داشته باشید که اگر تگ <iframe>
را مینویسید، وقتی شی YT.Player
را میسازید، نیازی به تعیین مقادیر برای width
و height
ندارید که به عنوان ویژگیهای تگ <iframe>
یا videoId
مشخص میشوند. و پارامترهای پخش کننده، که در URL src
مشخص شده اند. به عنوان یک اقدام امنیتی اضافی، باید پارامتر origin
را نیز به URL وارد کنید و طرح URL ( http://
یا https://
) و دامنه کامل صفحه میزبان خود را به عنوان مقدار پارامتر مشخص کنید. در حالی که origin
اختیاری است، از جمله در برابر تزریق جاوا اسکریپت شخص ثالث مخرب به صفحه شما و ربودن کنترل پخش کننده YouTube شما محافظت می کند.
بخش Examples همچنین چند مثال دیگر را برای ساخت اشیاء پخش کننده ویدیو نشان می دهد.
برای فراخوانی متدهای پخش کننده API، ابتدا باید یک مرجع به شی پخش کننده ای که می خواهید کنترل کنید، دریافت کنید. شما مرجع را با ایجاد یک شیء YT.Player
همانطور که در بخش شروع و بارگیری یک پخش کننده ویدیو در این سند توضیح داده شده است، به دست می آورید.
عملکردهای صف به شما امکان بارگیری و پخش یک ویدیو، یک لیست پخش یا لیست دیگری از ویدیوها را می دهند. اگر از دستور شیء توضیح داده شده در زیر برای فراخوانی این توابع استفاده می کنید، می توانید لیستی از ویدیوهای آپلود شده کاربر را نیز در صف قرار دهید یا بارگذاری کنید.
API از دو نحو مختلف برای فراخوانی توابع صف پشتیبانی می کند.
نحو آرگومان نیاز دارد که آرگومان های تابع به ترتیبی تعیین شده فهرست شوند.
نحو شی به شما امکان می دهد یک شی را به عنوان یک پارامتر واحد ارسال کنید و ویژگی های شی را برای آرگومان های تابعی که می خواهید تنظیم کنید تعریف کنید. علاوه بر این، API ممکن است از عملکرد اضافی پشتیبانی کند که نحو آرگومان از آن پشتیبانی نمی کند.
برای مثال، تابع loadVideoById
را می توان به یکی از روش های زیر فراخوانی کرد. توجه داشته باشید که نحو شی از ویژگی endSeconds
پشتیبانی می کند، که نحو آرگومان آن را پشتیبانی نمی کند.
نحو آرگومان
loadVideoById("bHQqvYy5KYo", 5, "large")
نحو شی
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60});
-
cueVideoById
نحو آرگومان
player.cueVideoById(videoId:String, startSeconds:Number):Void
نحو شی
player.cueVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
این عملکرد تصویر کوچک ویدیوی مشخص شده را بارگیری می کند و پخش کننده را برای پخش ویدیو آماده می کند. پخش کننده تا زمانی که
playVideo()
یاseekTo()
فراخوانی نشود، FLV را درخواست نمی کند.- پارامتر
videoId
مورد نیاز، شناسه ویدیوی YouTube را برای پخش مشخص می کند. در YouTube Data API، ویژگیid
یک منبعvideo
، شناسه را مشخص میکند. - پارامتر اختیاری
startSeconds
یک float/integer را میپذیرد و زمانی را مشخص میکند که پس از فراخوانیplayVideo()
باید پخش ویدیو شروع شود. اگر مقدارstartSeconds
را مشخص کنید و سپسseekTo()
را فراخوانی کنید، پخش کننده از زمان مشخص شده در فراخوانseekTo()
بازی می کند. هنگامی که ویدیو آماده شد و برای پخش آماده شد، پخش کننده یک رویدادvideo cued
پخش خواهد کرد (5
). - پارامتر اختیاری
endSeconds
، که فقط در نحو شی پشتیبانی میشود، یک عدد float/integer را میپذیرد و زمانی را مشخص میکند که پخش ویدیو با فراخوانیplayVideo()
متوقف شود. اگر مقدارendSeconds
را مشخص کنید و سپسseekTo()
را فراخوانی کنید، مقدارendSeconds
دیگر اعمال نخواهد شد.
loadVideoById
نحو آرگومان
player.loadVideoById(videoId:String, startSeconds:Number):Void
نحو شی
player.loadVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
این تابع ویدیوی مشخص شده را بارگیری و پخش می کند.
- پارامتر
videoId
مورد نیاز، شناسه ویدیوی YouTube را برای پخش مشخص می کند. در YouTube Data API، ویژگیid
یک منبعvideo
، شناسه را مشخص میکند. - پارامتر اختیاری
startSeconds
یک float/integer را می پذیرد. اگر مشخص باشد، ویدئو از نزدیکترین فریم کلیدی به زمان مشخص شده شروع می شود. - پارامتر اختیاری
endSeconds
یک float/integer را می پذیرد. اگر مشخص شده باشد، پخش ویدیو در زمان مشخص شده متوقف می شود.
cueVideoByUrl
نحو آرگومان
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
نحو شی
player.cueVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
این عملکرد تصویر کوچک ویدیوی مشخص شده را بارگیری می کند و پخش کننده را برای پخش ویدیو آماده می کند. پخش کننده تا زمانی که
playVideo()
یاseekTo()
فراخوانی نشود، FLV را درخواست نمی کند.- پارامتر
mediaContentUrl
مورد نیاز یک URL پخش کننده YouTube کاملا واجد شرایط را در قالبhttp://www.youtube.com/v/VIDEO_ID?version=3
مشخص می کند. - پارامتر اختیاری
startSeconds
یک float/integer را میپذیرد و زمانی را مشخص میکند که پس از فراخوانیplayVideo()
باید پخش ویدیو شروع شود. اگرstartSeconds
مشخص کنید و سپسseekTo()
را فراخوانی کنید، سپس پخش کننده از زمان مشخص شده در فراخوانseekTo()
پخش می شود. هنگامی که ویدئو آماده شد و برای پخش آماده شد، پخش کننده یک رویدادvideo cued
(5) را پخش خواهد کرد. - پارامتر اختیاری
endSeconds
، که فقط در نحو شی پشتیبانی میشود، یک عدد float/integer را میپذیرد و زمانی را مشخص میکند که پخش ویدیو با فراخوانیplayVideo()
متوقف شود. اگر مقدارendSeconds
را مشخص کنید و سپسseekTo()
را فراخوانی کنید، مقدارendSeconds
دیگر اعمال نخواهد شد.
loadVideoByUrl
نحو آرگومان
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
نحو شی
player.loadVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
این تابع ویدیوی مشخص شده را بارگیری و پخش می کند.
- پارامتر
mediaContentUrl
مورد نیاز یک URL پخش کننده YouTube کاملا واجد شرایط را در قالبhttp://www.youtube.com/v/VIDEO_ID?version=3
مشخص می کند. - پارامتر اختیاری
startSeconds
یک float/integer را میپذیرد و زمان شروع پخش ویدیو را مشخص میکند. اگرstartSeconds
(عدد می تواند شناور باشد) مشخص شده باشد، ویدیو از نزدیکترین فریم کلیدی به زمان مشخص شده شروع می شود. - پارامتر اختیاری
endSeconds
، که فقط در نحو شی پشتیبانی میشود، یک عدد شناور/صحیح را میپذیرد و زمان توقف پخش ویدیو را مشخص میکند.
توابع cuePlaylist
و loadPlaylist
به شما این امکان را می دهند که یک لیست پخش را بارگیری و پخش کنید. اگر از دستور شی برای فراخوانی این توابع استفاده می کنید، می توانید لیستی از ویدیوهای آپلود شده کاربر را نیز در صف قرار دهید (یا بارگذاری کنید).
از آنجایی که توابع بسته به اینکه با استفاده از نحو آرگومان فراخوانی شوند یا نحو شیء متفاوت عمل می کنند، هر دو روش فراخوانی در زیر مستند شده اند.
-
cuePlaylist
نحو آرگومان
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
لیست پخش مشخص شده را در صف قرار می دهد. وقتی لیست پخش آماده شد و برای پخش آماده شد، پخش کننده یک رویدادvideo cued
را پخش می کند (5
).پارامتر
playlist
مورد نیاز آرایه ای از شناسه های ویدیوی YouTube را مشخص می کند. در YouTube Data API، ویژگیid
منبعvideo
، شناسه آن ویدیو را مشخص میکند.پارامتر
index
اختیاری، نمایه اولین ویدیویی را که در لیست پخش پخش میشود، مشخص میکند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض0
است، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیو در لیست پخش است.پارامتر اختیاری
startSeconds
یک عدد float/integer را میپذیرد و زمانی را مشخص میکند که اولین ویدیو در لیست پخش با فراخوانی تابعplayVideo()
باید پخش شود. اگر مقدارstartSeconds
را مشخص کنید و سپسseekTo()
را فراخوانی کنید، پخش کننده از زمان مشخص شده در فراخوانseekTo()
بازی می کند. اگر یک لیست پخش را انتخاب کنید و سپس تابعplayVideoAt()
را فراخوانی کنید، پخش کننده در ابتدای ویدیوی مشخص شده شروع به پخش می کند.
نحو شی
player.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number}):Void
لیست مشخص شده ویدیوها را در صف قرار می دهد. این لیست می تواند یک لیست پخش یا فید ویدیوهای آپلود شده کاربر باشد. قابلیت صفبندی فهرستی از نتایج جستجو منسوخ شده است و از15 نوامبر 2020 دیگر پشتیبانی نخواهد شد.هنگامی که لیست آماده شد و برای پخش آماده شد، پخش کننده یک رویداد
video cued
پخش می کند (5
).ویژگی اختیاری
listType
نوع فید نتایجی را که بازیابی می کنید مشخص می کند. مقادیر معتبرplaylist
وuser_uploads
هستند. یک مقدار منسوخ،search
، از15 نوامبر 2020 دیگر پشتیبانی نخواهد شد. مقدار پیش فرضplaylist
است.ویژگی
list
مورد نیاز حاوی کلیدی است که لیست خاصی از ویدیوهایی را که YouTube باید برگرداند را مشخص می کند.- اگر مقدار ویژگی
listType
playlist
باشد، ویژگیlist
شناسه لیست پخش یا آرایه ای از شناسه های ویدیو را مشخص می کند. در YouTube Data API، ویژگیid
منبعplaylist
، شناسه فهرست پخش را مشخص میکند، و ویژگیid
منبعvideo
، شناسه ویدیو را مشخص میکند. - اگر مقدار ویژگی
listType
user_uploads
باشد، ویژگیlist
کاربری را مشخص می کند که ویدیوهای آپلود شده او برگردانده می شوند. - اگر مقدار ویژگی
listType
search
باشد، ویژگیlist
عبارت جستجو را مشخص می کند. توجه: این عملکرد منسوخ شده است و از15 نوامبر 2020 دیگر پشتیبانی نخواهد شد.
- اگر مقدار ویژگی
ویژگی
index
اختیاری، نمایه اولین ویدیویی که در لیست پخش می شود را مشخص می کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض0
است، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیو در لیست است.ویژگی اختیاری
startSeconds
یک عدد float/integer را میپذیرد و زمانی را مشخص میکند که اولین ویدیوی لیست باید از آن زمان شروع به پخش کند که تابعplayVideo()
فراخوانی شود. اگر مقدارstartSeconds
را مشخص کنید و سپسseekTo()
را فراخوانی کنید، پخش کننده از زمان مشخص شده در فراخوانseekTo()
بازی می کند. اگر لیستی را علامت بزنید و سپس تابعplayVideoAt()
را فراخوانی کنید، پخش کننده در ابتدای ویدیوی مشخص شده شروع به پخش می کند.
-
loadPlaylist
نحو آرگومان
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
این تابع لیست پخش مشخص شده را بارگیری می کند و آن را پخش می کند.پارامتر
playlist
مورد نیاز آرایه ای از شناسه های ویدیوی YouTube را مشخص می کند. در YouTube Data API، ویژگیid
منبعvideo
، شناسه ویدیو را مشخص میکند.پارامتر
index
اختیاری، نمایه اولین ویدیویی را که در لیست پخش پخش میشود، مشخص میکند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض0
است، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیو در لیست پخش است.پارامتر اختیاری
startSeconds
یک float/integer را میپذیرد و زمانی را مشخص میکند که اولین ویدیو در لیست پخش باید از آن زمان شروع به پخش کند.
نحو شی
player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number}):Void
این تابع لیست مشخص شده را بارگیری می کند و آن را پخش می کند. این لیست می تواند یک لیست پخش یا فید ویدیوهای آپلود شده کاربر باشد. امکان بارگیری فهرستی از نتایج جستجو منسوخ شده است و از15 نوامبر 2020 دیگر پشتیبانی نخواهد شد.ویژگی اختیاری
listType
نوع فید نتایجی را که بازیابی می کنید مشخص می کند. مقادیر معتبرplaylist
وuser_uploads
هستند. یک مقدار منسوخ،search
، از15 نوامبر 2020 دیگر پشتیبانی نخواهد شد. مقدار پیش فرضplaylist
است.ویژگی
list
مورد نیاز حاوی کلیدی است که لیست خاصی از ویدیوهایی را که YouTube باید برگرداند را مشخص می کند.- اگر مقدار ویژگی
listType
playlist
باشد، ویژگیlist
یک شناسه لیست پخش یا آرایهای از شناسههای ویدیو را مشخص میکند. در YouTube Data API، ویژگیid
منبعplaylist
شناسه فهرست پخش را مشخص میکند، و ویژگیid
منبعvideo
، شناسه ویدیو را مشخص میکند. - اگر مقدار ویژگی
listType
user_uploads
باشد، ویژگیlist
کاربری را مشخص می کند که ویدیوهای آپلود شده او برگردانده می شوند. - اگر مقدار ویژگی
listType
search
باشد، ویژگیlist
عبارت جستجو را مشخص می کند. توجه: این عملکرد منسوخ شده است و از15 نوامبر 2020 دیگر پشتیبانی نخواهد شد.
- اگر مقدار ویژگی
ویژگی
index
اختیاری، نمایه اولین ویدیویی که در لیست پخش می شود را مشخص می کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض0
است، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیو در لیست است.ویژگی اختیاری
startSeconds
یک float/integer را میپذیرد و زمانی را مشخص میکند که اولین ویدیوی فهرست باید پخش شود.
-
player. playVideo ():Void
- ویدیوی نمایش داده شده/بارگذاری شده فعلی را پخش می کند. حالت نهایی پخش کننده پس از اجرای این تابع
playing
(1) خواهد بود.
توجه: بازپخش تنها در صورتی در تعداد بازدیدهای رسمی ویدیو به حساب می آید که از طریق دکمه پخش بومی در پخش کننده شروع شود.
-
player. pauseVideo ():Void
- ویدیوی در حال پخش را متوقف می کند. حالت نهایی پخش کننده پس از اجرای این تابع
paused
می شود (2
) مگر اینکه هنگام فراخوانی تابع، پخش کننده در حالتended
(0
) باشد، در این صورت وضعیت پخش تغییر نخواهد کرد.
-
player. stopVideo ():Void
- بارگیری ویدیوی فعلی را متوقف و لغو می کند. این عملکرد باید برای موقعیتهای نادری که میدانید کاربر ویدیوی اضافی را در پخشکننده تماشا نخواهد کرد، رزرو شود. اگر قصد شما توقف موقت ویدیو است، فقط باید تابع
pauseVideo
فراخوانی کنید. اگر میخواهید ویدیویی را که پخشکننده در حال پخش است تغییر دهید، میتوانید بدون تماس باstopVideo
ابتدا یکی از عملکردهای صف را فراخوانی کنید.
مهم: برخلاف عملکردpauseVideo
که پخش کننده را در حالتpaused
(2
) قرار می دهد، عملکردstopVideo
می تواند پخش کننده را در حالت عدم پخش قرار دهد، از جملهended
(0
)،paused
(2
)،video cued
(5
) یاunstarted
(-1
).
-
player. seekTo (seconds:Number, allowSeekAhead:Boolean):Void
- به دنبال زمان مشخصی در ویدیو است. اگر پخش کننده هنگام فراخوانی عملکرد متوقف شود، متوقف می شود. اگر عملکرد از حالت دیگری فراخوانی شود (در حال
playing
،video cued
، و غیره)، پخش کننده ویدیو را پخش می کند.پارامتر
seconds
زمانی را مشخص می کند که بازیکن باید تا آن پیش برود.پخشکننده قبل از آن زمان به نزدیکترین فریم کلیدی میرود، مگر اینکه پخشکننده قبلاً بخشی از ویدیویی را که کاربر به دنبال آن است دانلود کرده باشد.
پارامتر
allowSeekAhead
تعیین میکند که اگر پارامترseconds
زمانی خارج از دادههای ویدئویی بافر فعلی را مشخص کند، پخشکننده درخواست جدیدی به سرور ارسال کند یا خیر.توصیه میکنیم زمانی که کاربر ماوس را در نوار پیشرفت ویدیو میکشد، این پارامتر را روی
false
تنظیم کنید و زمانی که کاربر ماوس را رها کرد، آن را رویtrue
تنظیم کنید. این رویکرد به کاربر اجازه میدهد تا با پیمایش نقاط بافر نشده در ویدیو، به نقاط مختلف ویدیو بدون درخواست پخش جریانی جدید ویدیو پیمایش کند. هنگامی که کاربر دکمه ماوس را رها می کند، پخش کننده به نقطه مورد نظر در ویدیو پیش می رود و در صورت لزوم درخواست پخش ویدیوی جدید می کند.
توجه: تجربه پخش ویدیوی 360 درجه در دستگاه های تلفن همراه پشتیبانی محدودی دارد. در دستگاههای پشتیبانینشده، ویدیوهای 360 درجه تحریف شده به نظر میرسند و اصلاً هیچ روش پشتیبانیشدهای برای تغییر زاویه دید وجود ندارد، از جمله از طریق API، استفاده از حسگرهای جهتیابی، یا پاسخ به اقدامات لمسی/کشیدن روی صفحهنمایش دستگاه.
-
player. getSphericalProperties ():Object
- ویژگی هایی را بازیابی می کند که دیدگاه یا نمای فعلی بیننده را برای پخش ویدیو توصیف می کند. علاوه بر این:
- این شی فقط برای ویدیوهای 360 درجه پر شده است که به آنها ویدیوهای کروی نیز می گویند.
- اگر ویدیوی فعلی یک ویدیوی 360 درجه نیست یا اگر عملکرد از یک دستگاه پشتیبانی نشده فراخوانی شود، تابع یک شی خالی را برمیگرداند.
- در دستگاههای تلفن همراه پشتیبانیشده، اگر ویژگی
enableOrientationSensor
رویtrue
تنظیم شود، این تابع یک شی را برمیگرداند که در آن ویژگیfov
حاوی مقدار صحیح است و سایر ویژگیها روی0
تنظیم شدهاند.
خواص yaw
عددی در محدوده [0، 360) که زاویه افقی دید را بر حسب درجه نشان میدهد، که نشاندهنده میزان چرخش کاربر به سمت چپ یا راست است. موقعیت خنثی، رو به مرکز ویدیو در نمای مستطیلی آن، نشان دهنده 0 درجه است، و این مقدار با چرخش بیننده به چپ افزایش می یابد. pitch
عددی در محدوده [90-، 90] که زاویه عمودی دید را بر حسب درجه نشان میدهد، که نشاندهنده میزانی است که کاربر نما را برای نگاه کردن به بالا یا پایین تنظیم میکند. موقعیت خنثی، رو به مرکز ویدیو در طرح ریزی مستطیل شکل آن، نشان دهنده 0 درجه است، و این مقدار با نگاه کردن بیننده به بالا افزایش می یابد. roll
عددی در محدوده [-180، 180] که زاویه چرخش در جهت عقربههای ساعت یا خلاف جهت عقربههای ساعت را بر حسب درجه نشان میدهد. موقعیت خنثی، با محور افقی در برآمدگی مستطیل شکل موازی با محور افقی نما، نشان دهنده 0 درجه است. با چرخش نما در جهت عقربههای ساعت، مقدار افزایش مییابد و با چرخش نما در خلاف جهت عقربههای ساعت، مقدار آن کاهش مییابد.
توجه داشته باشید که پخش کننده تعبیه شده یک رابط کاربری برای تنظیم رول نمایش ارائه نمی دهد. رول را می توان به یکی از این روش های متقابل منحصر به فرد تنظیم کرد:- از حسگر جهت یابی در مرورگر تلفن همراه برای ارائه رول برای نما استفاده کنید. اگر سنسور جهت گیری فعال باشد، تابع
getSphericalProperties
همیشه0
به عنوان مقدار ویژگیroll
برمی گرداند. - اگر سنسور جهت غیرفعال است، با استفاده از این API، رول را روی یک مقدار غیر صفر تنظیم کنید.
fov
عددی در محدوده [30، 120] که میدان دید نمای را بر حسب درجه نشان میدهد که در امتداد لبه بلندتر نمای درگاه اندازهگیری میشود. لبه کوتاهتر بهطور خودکار تنظیم میشود تا متناسب با نسبت تصویر باشد.
مقدار پیش فرض 100 درجه است. کاهش مقدار مانند بزرگنمایی محتوای ویدیویی است و افزایش مقدار مانند بزرگنمایی است. این مقدار را می توان با استفاده از API یا با استفاده از چرخ ماوس هنگامی که ویدیو در حالت تمام صفحه است تنظیم کرد.
-
player. setSphericalProperties (properties:Object):Void
- جهت ویدیو را برای پخش یک ویدیوی 360 درجه تنظیم می کند. (اگر ویدیوی فعلی کروی نباشد، روش بدون در نظر گرفتن ورودی، بدون عملیات است.)
نمای پخش کننده با به روز رسانی به فراخوانی های این روش پاسخ می دهد تا مقادیر هر ویژگی شناخته شده در شیءproperties
را منعکس کند. این view مقادیری را برای هر ویژگی شناخته شده دیگری که در آن شی گنجانده نشده است حفظ می کند.
علاوه بر این:- اگر شی حاوی ویژگی های ناشناخته و/یا غیرمنتظره باشد، بازیکن آنها را نادیده می گیرد.
- همانطور که در ابتدای این بخش ذکر شد، تجربه پخش ویدیوی 360 درجه در همه دستگاه های تلفن همراه پشتیبانی نمی شود.
- بهطور پیشفرض، در دستگاههای تلفن همراه پشتیبانیشده، این تابع مجموعهها فقط ویژگی
fov
را تنظیم میکند و بر ویژگیهایyaw
،pitch
وroll
برای پخش ویدیوی 360 درجه تأثیر نمیگذارد. برای جزئیات بیشتر به ویژگیenableOrientationSensor
در زیر مراجعه کنید.
properties
ارسال شده به تابع حاوی ویژگی های زیر است:خواص yaw
به تعریف بالا مراجعه کنید. pitch
به تعریف بالا مراجعه کنید. roll
به تعریف بالا مراجعه کنید. fov
به تعریف بالا مراجعه کنید. enableOrientationSensor
توجه: این ویژگی فقط بر روی تجربه مشاهده 360 درجه در دستگاه های پشتیبانی شده تأثیر می گذارد. یک مقدار بولی که نشان میدهد آیا تعبیهشده IFrame باید به رویدادهایی که سیگنال تغییرات در جهت دستگاه پشتیبانیشده را نشان میدهند، مانند DeviceOrientationEvent
مرورگر تلفن همراه پاسخ دهد. مقدار پارامتر پیش فرضtrue
است.
دستگاه های تلفن همراه پشتیبانی شده- وقتی مقدار
true
باشد، پخشکننده تعبیهشده تنها به حرکت دستگاه تکیه میکند تا ویژگیهایyaw
،pitch
وroll
برای پخش ویدیوی 360 درجه تنظیم کند. با این حال، ویژگیfov
را هنوز می توان از طریق API تغییر داد، و API در واقع تنها راه برای تغییر ویژگیfov
در یک دستگاه تلفن همراه است. این رفتار به طور پیش فرض است. - وقتی مقدار
false
است، حرکت دستگاه بر تجربه مشاهده 360 درجه تأثیر نمیگذارد و ویژگیهایyaw
،pitch
،roll
وfov
همگی باید از طریق API تنظیم شوند.
دستگاه های تلفن همراه پشتیبانی نشده
مقدار ویژگیenableOrientationSensor
هیچ تاثیری بر تجربه پخش ندارد.
-
player. nextVideo ():Void
- این تابع ویدیوی بعدی را در لیست پخش بارگیری و پخش می کند.
اگر
player.nextVideo()
در حالی که آخرین ویدیو در لیست پخش در حال مشاهده است فراخوانی شود، و لیست پخش برای پخش مداوم (loop
) تنظیم شده باشد، پخش کننده اولین ویدیوی لیست را بارگیری و پخش می کند.اگر
player.nextVideo()
در حالی که آخرین ویدیو در لیست پخش در حال مشاهده است فراخوانی شود و لیست پخش برای پخش مداوم تنظیم نشده باشد، پخش به پایان می رسد.
-
player. previousVideo ():Void
- این عملکرد ویدیوی قبلی را در لیست پخش بارگیری و پخش می کند.
اگر
player.previousVideo()
در حالی که اولین ویدیو در لیست پخش در حال تماشا است فراخوانی شود، و لیست پخش به طور مداوم پخش شود (loop
)، پخش کننده آخرین ویدیوی لیست را بارگیری و پخش می کند.اگر
player.previousVideo()
در حالی که اولین ویدیو در لیست پخش در حال مشاهده است فراخوانی شود و لیست پخش برای پخش مداوم تنظیم نشده باشد، پخش کننده اولین ویدیوی لیست پخش را از ابتدا مجدداً راه اندازی می کند.
-
player. playVideoAt (index:Number):Void
- این عملکرد ویدیوی مشخص شده را در لیست پخش بارگیری و پخش می کند.
پارامتر
index
مورد نیاز نمایه ویدیویی را که می خواهید در لیست پخش پخش کنید مشخص می کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند، بنابراین مقدار0
اولین ویدیو را در لیست مشخص می کند. اگر لیست پخش را به هم ریخته باشید، این عملکرد ویدیو را در موقعیت مشخص شده در لیست پخش به هم ریخته پخش می کند.
-
player. mute ():Void
- پخش کننده را بی صدا می کند.
-
player. unMute ():Void
- صدای پخش کننده را لغو می کند.
-
player. isMuted ():Boolean
- اگر پخش کننده بی صدا باشد
true
، در غیر این صورتfalse
برمی گرداند.
-
player. setVolume (volume:Number):Void
- میزان صدا را تنظیم می کند. عدد صحیح بین
0
تا100
را می پذیرد.
-
player. getVolume ():Number
- حجم فعلی پخش کننده، عددی صحیح بین
0
تا100
را برمی گرداند. توجه داشته باشید کهgetVolume()
حجم صدا را برمی گرداند حتی اگر پخش کننده بی صدا باشد.
-
player.setSize(width:Number, height:Number):Object
- اندازه
<iframe>
را که حاوی پخش کننده است بر حسب پیکسل تنظیم می کند.
-
player. getPlaybackRate ():Number
- این عملکرد نرخ پخش ویدیوی در حال پخش را بازیابی می کند. نرخ پخش پیشفرض
1
است که نشان میدهد ویدیو با سرعت عادی پخش میشود. نرخ پخش ممکن است شامل مقادیری مانند0.25
،0.5
،1
،1.5
، و2
باشد.
-
player. setPlaybackRate (suggestedRate:Number):Void
- این تابع نرخ پخش پیشنهادی را برای ویدیوی فعلی تنظیم می کند. اگر نرخ پخش تغییر کند، فقط برای ویدیویی که قبلاً نمایش داده شده یا در حال پخش است تغییر می کند. اگر نرخ پخش را برای یک ویدیوی نمایشی تنظیم کنید، زمانی که عملکرد
playVideo
فراخوانی می شود یا کاربر پخش را مستقیماً از طریق کنترل های پخش کننده شروع می کند، این نرخ همچنان فعال خواهد بود. علاوه بر این، فراخوانی توابع برای نمایش یا بارگیری ویدیوها یا لیستهای پخش (cueVideoById
،loadVideoById
، و غیره) نرخ پخش را به1
بازنشانی میکند.
فراخوانی این عملکرد تضمین نمی کند که نرخ پخش واقعاً تغییر کند. با این حال، اگر نرخ پخش تغییر کند، رویدادonPlaybackRateChange
فعال میشود و کد شما باید به رویداد پاسخ دهد نه اینکه تابعsetPlaybackRate
را فراخوانی کند.
روشgetAvailablePlaybackRates
نرخ پخش احتمالی ویدیوی در حال پخش را برمی گرداند. با این حال، اگر پارامترsuggestedRate
را روی یک عدد صحیح یا مقدار شناور غیرپشتیبانینشده تنظیم کنید، بازیکن آن مقدار را به نزدیکترین مقدار پشتیبانی شده در جهت1
گرد میکند.
-
player. getAvailablePlaybackRates ():Array
- این تابع مجموعه نرخهای پخشی را که ویدیوی فعلی در آن موجود است را برمیگرداند. مقدار پیش فرض
1
است که نشان می دهد ویدیو با سرعت عادی پخش می شود.
این تابع آرایه ای از اعداد مرتب شده از کندترین به سریعترین سرعت پخش را برمی گرداند. حتی اگر پخش کننده از سرعت پخش متغیر پشتیبانی نکند، آرایه همیشه باید حداقل یک مقدار (1
) داشته باشد.
-
player. setLoop (loopPlaylists:Boolean):Void
این عملکرد نشان می دهد که آیا پخش کننده ویدیو باید به طور مداوم یک لیست پخش را پخش کند یا اینکه پس از پایان آخرین ویدیو در لیست پخش، پخش آن متوقف شود. رفتار پیش فرض این است که لیست های پخش حلقه نمی شوند.
این تنظیم حتی اگر یک لیست پخش متفاوت را بارگیری یا نشانه گذاری کنید، ادامه خواهد داشت، به این معنی که اگر یک لیست پخش را بارگیری کنید، تابع
setLoop
را با مقدارtrue
فراخوانی کنید و سپس لیست پخش دوم را بارگیری کنید، لیست پخش دوم نیز حلقه خواهد شد.پارامتر
loopPlaylists
مورد نیاز رفتار حلقه را مشخص می کند.اگر مقدار پارامتر
true
باشد، پخش کننده ویدیو به طور مداوم لیست های پخش را پخش می کند. پس از پخش آخرین ویدیو در یک لیست پخش، پخش کننده ویدیو به ابتدای لیست پخش برمی گردد و دوباره آن را پخش می کند.اگر مقدار پارامتر
false
باشد، پس از اینکه پخش کننده ویدیو آخرین ویدیو را در یک لیست پخش پخش کرد، بازپخش پایان می یابد.
-
player. setShuffle (shufflePlaylist:Boolean):Void
این عملکرد نشان می دهد که آیا ویدیوهای یک لیست پخش باید به هم ریخته شوند تا به ترتیبی متفاوت از ترتیبی که سازنده لیست پخش تعیین کرده پخش شوند. اگر یک لیست پخش را بعد از شروع پخش آن به هم بزنید، تا زمانی که ویدیوی در حال پخش به پخش ادامه میدهد، فهرست دوباره مرتب میشود. سپس ویدیوی بعدی که پخش میشود بر اساس فهرستی که مرتب شده است انتخاب میشود.
اگر لیست پخش دیگری را بارگیری کنید یا علامت بزنید، این تنظیم ادامه نخواهد داشت، به این معنی که اگر یک لیست پخش را بارگیری کنید، تابع
setShuffle
را فراخوانی کنید و سپس لیست پخش دوم را بارگیری کنید، لیست پخش دوم به هم ریخته نخواهد شد.پارامتر
shufflePlaylist
مورد نیاز نشان می دهد که آیا YouTube باید لیست پخش را به هم بزند یا خیر.اگر مقدار پارامتر
true
باشد، YouTube ترتیب لیست پخش را تغییر می دهد. اگر به این تابع دستور دهید تا لیست پخشی را که قبلاً به هم ریخته شده است به هم بزند، YouTube دوباره ترتیب را به هم میزند.اگر مقدار پارامتر
false
باشد، YouTube ترتیب لیست پخش را به ترتیب اصلی خود تغییر خواهد داد.
-
player. getVideoLoadedFraction ():Float
- عددی بین
0
و1
را برمیگرداند که درصد ویدیویی را که پخشکننده بهعنوان بافر نشان میدهد، مشخص میکند. این روش عدد قابل اعتمادتری را نسبت به متدهایgetVideoBytesLoaded
وgetVideoBytesTotal
که اکنون منسوخ شده اند، برمی گرداند.
-
player.getPlayerState():Number
- وضعیت بازیکن را برمیگرداند. مقادیر ممکن عبارتند از:
-
-1
- شروع نشده است -
0
- پایان یافت -
1
- بازی کردن -
2
مکث کرد -
3
بافر کردن -
5
- تصویری cued
-
-
player. getCurrentTime ():Number
- زمان سپری شده از زمان شروع پخش ویدیو را بر حسب ثانیه برمی گرداند.
-
player. getVideoStartBytes ():Number
- از 31 اکتبر 2012 منسوخ شده است. تعداد بایت هایی را که فایل ویدیویی از آنها بارگیری شده است را برمی گرداند. (این روش اکنون همیشه مقدار
0
را برمی گرداند.) سناریوی مثال: کاربر به دنبال نقطه ای است که هنوز بارگیری نشده است، و بازیکن درخواست جدیدی برای پخش بخشی از ویدیویی که هنوز بارگذاری نشده است ارائه می دهد.
-
player. getVideoBytesLoaded ():Number
- از 18 ژوئیه 2012 منسوخ شده است. در عوض، از روش
getVideoLoadedFraction
برای تعیین درصد ویدیویی که بافر شده است استفاده کنید.
این روش مقداری بین0
تا1000
برمیگرداند که تقریباً مقدار ویدیویی که بارگذاری شده است را نشان میدهد. با تقسیم مقدارgetVideoBytesLoaded
بر مقدارgetVideoBytesTotal
میتوانید کسری از ویدیوی بارگذاری شده را محاسبه کنید.
-
player. getVideoBytesTotal ():Number
- از 18 ژوئیه 2012 منسوخ شده است. در عوض، از روش
getVideoLoadedFraction
برای تعیین درصد ویدیویی که بافر شده است استفاده کنید.
اندازه ویدیوی بارگیری/در حال پخش یا تقریبی اندازه ویدیو را بر حسب بایت برمیگرداند.
این روش همیشه مقدار1000
را برمی گرداند. با تقسیم مقدارgetVideoBytesLoaded
بر مقدارgetVideoBytesTotal
میتوانید کسری از ویدیوی بارگذاری شده را محاسبه کنید.
-
player. getDuration ():Number
- مدت زمان ویدیوی در حال پخش را بر حسب ثانیه برمیگرداند. توجه داشته باشید که
getDuration()
تا زمانی که ابرداده ویدیو بارگیری شود0
برمی گردد، که معمولاً درست پس از شروع پخش ویدیو اتفاق می افتد.
اگر ویدیوی در حال پخش یک رویداد زنده باشد، تابعgetDuration()
زمان سپری شده از شروع پخش زنده ویدیو را برمی گرداند. به طور خاص، این مدت زمانی است که ویدیو بدون تنظیم مجدد یا قطع شده است. علاوه بر این، این مدت معمولاً بیشتر از زمان واقعی رویداد است زیرا پخش جریانی ممکن است قبل از زمان شروع رویداد شروع شود.
-
player. getVideoUrl ():String
- URL YouTube.com را برای ویدیوی بارگیری/در حال پخش برمیگرداند.
-
player. getVideoEmbedCode ():String
- کد جاسازی شده را برای ویدیوی بارگیری/در حال پخش برمیگرداند.
-
player. getPlaylist ():Array
- این تابع آرایه ای از شناسه های ویدیویی موجود در لیست پخش را همانطور که در حال حاضر مرتب شده اند، برمی گرداند. بهطور پیشفرض، این تابع شناسههای ویدیو را به ترتیبی که مالک فهرست پخش تعیین کرده است، برمیگرداند. با این حال، اگر تابع
setShuffle
را برای به هم زدن ترتیب لیست پخش فراخوانی کرده باشید، سپس مقدار بازگشتی تابعgetPlaylist()
ترتیب به هم ریخته را منعکس خواهد کرد.
-
player. getPlaylistIndex ():Number
- این عملکرد شاخص فیلم لیست پخش را که در حال حاضر پخش می شود ، برمی گرداند.
اگر لیست پخش را تغییر نداده اید ، مقدار بازگشت موقعیتی را که خالق لیست پخش فیلم را قرار داده است ، مشخص می کند. مقدار بازگشت از یک شاخص مبتنی بر صفر استفاده می کند ، بنابراین مقدار
0
اولین ویدیوی را در لیست پخش مشخص می کند.اگر لیست پخش را تغییر داده اید ، مقدار بازگشت سفارش فیلم را در لیست پخش شده در لیست پخش می کند.
-
player. addEventListener (event:String, listener:String):Void
- یک عملکرد شنونده را برای
event
مشخص اضافه می کند. بخش وقایع زیر وقایع مختلفی را که ممکن است بازیکن آتش سوزی کند مشخص می کند. شنونده رشته ای است که عملکردی را که هنگام آتش سوزی رویداد مشخص شده انجام می دهد ، مشخص می کند.
-
player. removeEventListener (event:String, listener:String):Void
- یک عملکرد شنونده را برای
event
مشخص شده حذف می کند.listener
رشته ای است که عملکردی را مشخص می کند که هنگام آتش سوزی رویداد مشخص دیگر اجرا نمی شود.
-
player. getIframe ():Object
- این روش گره DOM را برای
<iframe>
تعبیه شده برمی گرداند.
-
player. destroy ():Void
-
<iframe>
حاوی بازیکن را حذف می کند.
API رویدادهایی را برای اطلاع از تغییرات شما در بازیکن تعبیه شده آتش می زند. همانطور که در بخش قبلی ذکر شد ، می توانید با اضافه کردن یک شنونده رویداد هنگام ساخت شی YT.Player
، در رویدادها مشترک شوید و همچنین می توانید از عملکرد addEventListener
استفاده کنید.
API یک شیء رویداد را به عنوان تنها استدلال برای هر یک از این توابع منتقل می کند. شیء رویداد دارای خواص زیر است:
-
target
این رویداد پخش کننده ویدیویی را که مطابق با این رویداد است ، مشخص می کند. -
data
این رویداد مقداری مربوط به این رویداد را مشخص می کند. توجه داشته باشید که رویدادهایonReady
وonAutoplayBlocked
یک ویژگیdata
را مشخص نمی کنند.
لیست زیر وقایعی را که API آتش می گیرد تعریف می کند:
-
onReady
- این رویداد هر زمان که یک بازیکن بارگذاری را تمام کرده و آماده دریافت تماس های API است ، آتش می گیرد. اگر می خواهید به طور خودکار عملیات های خاصی مانند پخش ویدیو یا نمایش اطلاعات در مورد فیلم را به محض آماده شدن پخش کننده انجام دهید ، باید این عملکرد را پیاده سازی کنید.
مثال زیر یک عملکرد نمونه برای رسیدگی به این رویداد را نشان می دهد. شیء رویداد که API به عملکرد منتقل می کند ، دارای یک ویژگیtarget
است که بازیکن را مشخص می کند. این تابع کد تعبیه شده را برای ویدیوی بارگذاری شده در حال حاضر بازیابی می کند ، شروع به پخش فیلم می کند و کد جاسازی شده را در عنصر صفحه نمایش می دهد که دارای مقدارid
embed-code
است.function onPlayerReady(event) { var embedCode = event.target.getVideoEmbedCode(); event.target.playVideo(); if (document.getElementById('embed-code')) { document.getElementById('embed-code').innerHTML = embedCode; } }
-
onStateChange
- این رویداد هر زمان که حالت بازیکن تغییر کند آتش می گیرد. ویژگی
data
شیء رویداد که API به عملکرد شنونده رویداد شما منتقل می کند ، یک عدد صحیح را که مطابق با حالت پخش کننده جدید است ، مشخص می کند. مقادیر احتمالی عبارتند از:-
-1
(بدون برنامه) -
0
(پایان) -
1
(بازی) -
2
(مکث) -
3
(بافر) -
5
(ویدیو cued).
unstarted
(-1
) را پخش می کند. هنگامی که یک ویدیو کارد و آماده پخش است ، پخش کننده یک رویدادvideo cued
(5
) را پخش می کند. در کد خود می توانید مقادیر عدد صحیح را مشخص کنید یا می توانید از یکی از متغیرهای نام خانوادگی زیر استفاده کنید:-
YT.PlayerState.ENDED
-
YT.PlayerState.PLAYING
-
YT.PlayerState.PAUSED
-
YT.PlayerState.BUFFERING
-
YT.PlayerState.CUED
-
-
onPlaybackQualityChange
- این رویداد هر زمان که کیفیت پخش ویدیو تغییر می کند ، آتش می گیرد. این ممکن است نشانگر تغییر در محیط پخش بیننده باشد. برای کسب اطلاعات بیشتر در مورد عواملی که بر شرایط پخش تأثیر می گذارد یا ممکن است باعث آتش سوزی این رویداد شود ، به مرکز راهنمای YouTube مراجعه کنید.
مقدار خاصیتdata
شیء رویداد که API به عملکرد شنونده رویداد منتقل می کند ، رشته ای خواهد بود که کیفیت پخش جدید را مشخص می کند. مقادیر احتمالی عبارتند از:-
small
-
medium
-
large
-
hd720
-
hd1080
-
highres
-
-
onPlaybackRateChange
- این رویداد هر زمان که نرخ پخش ویدیو تغییر می کند آتش می گیرد. به عنوان مثال ، اگر شما با عملکرد
setPlaybackRate(suggestedRate)
تماس بگیرید ، اگر نرخ پخش در واقع تغییر کند ، این رویداد آتش می گیرد. برنامه شما باید به این رویداد پاسخ دهد و نباید تصور کند که با استفاده از عملکردsetPlaybackRate(suggestedRate)
نرخ پخش به طور خودکار تغییر خواهد کرد. به همین ترتیب ، کد شما نباید فرض کند که نرخ پخش ویدیو فقط در نتیجه یک تماس صریح برایsetPlaybackRate
تغییر خواهد کرد.
مقدار خاصیتdata
شیء رویداد که API به عملکرد شنونده رویداد منتقل می کند ، عددی خواهد بود که نرخ پخش جدید را مشخص می کند. روشgetAvailablePlaybackRates
لیستی از نرخ پخش معتبر را برای فیلم Cust یا Clued یا Playing بازگرداند.
-
onError
- در صورت بروز خطایی در بازیکن ، این رویداد آتش می گیرد. API یک شیء
event
را به عملکرد شنونده رویداد منتقل می کند. خاصیتdata
این شیء یک عدد صحیح را مشخص می کند که نوع خطایی را که رخ داده است مشخص می کند. مقادیر احتمالی عبارتند از:-
2
- درخواست حاوی یک مقدار پارامتر نامعتبر است. به عنوان مثال ، اگر یک شناسه ویدیویی را که 11 کاراکتر ندارد ، یا اگر شناسه ویدیویی حاوی کاراکترهای نامعتبر مانند نقاط تعجب یا ستاره ها باشد ، این خطا رخ می دهد. -
5
- محتوای درخواست شده را نمی توان در یک پخش کننده HTML5 یا خطای دیگری در رابطه با پخش کننده HTML5 پخش کرد. -
100
- فیلم درخواست شده پیدا نشد. این خطا هنگامی رخ می دهد که یک فیلم حذف شده است (به هر دلیلی) یا به عنوان خصوصی مشخص شده است. -
101
- صاحب فیلم درخواست شده اجازه نمی دهد که در بازیکنان تعبیه شده پخش شود. -
150
- این خطا همان101
است. این فقط یک خطای101
در مبدل است!
-
-
onApiChange
- این رویداد اخراج شده است تا نشان دهد بازیکن ماژول با روشهای API در معرض بار (یا بارگیری) بارگذاری کرده است. برنامه شما می تواند به این رویداد گوش کند و سپس بازیکن را برای تعیین اینکه کدام گزینه ها برای ماژول اخیراً بارگذاری شده در معرض دید قرار می گیرد ، نظرسنجی کنید. سپس برنامه شما می تواند تنظیمات موجود را برای آن گزینه ها بازیابی یا به روز کند.
دستور زیر مجموعه ای از نام های ماژول را بازیابی می کند که می توانید گزینه های پخش کننده را تنظیم کنید:
player.getOptions();
در حال حاضر ، تنها ماژول ای که می توانید گزینه هایی را برای آن تنظیم کنید ، ماژولcaptions
است که زیرنویس بسته در بازیکن را کنترل می کند. پس از دریافت یک رویدادonApiChange
، برنامه شما می تواند از دستور زیر استفاده کند تا مشخص کند کدام گزینه ها را می توان برای ماژولcaptions
تنظیم کرد:
player.getOptions('captions');
با نظرسنجی بازیکن با این دستور ، می توانید تأیید کنید که گزینه هایی که می خواهید به آن دسترسی پیدا کنید ، در واقع قابل دسترسی است. دستورات زیر گزینه های ماژول را بازیابی و به روز می کنند:
Retrieving an option: player.getOption(module, option); Setting an option player.setOption(module, option, value);
جدول زیر گزینه هایی را که API پشتیبانی می کند ذکر کرده است:مدول گزینه شرح captions fontSize این گزینه اندازه قلم زیرنویس های نمایش داده شده در پخش کننده را تنظیم می کند.
مقادیر معتبر-1
،0
،1
،2
و3
هستند. اندازه پیش فرض0
و کوچکترین اندازه-1
است. تنظیم این گزینه در یک عدد صحیح زیر-1
باعث می شود کوچکترین اندازه زیرنویس نمایش داده شود ، در حالی که تنظیم این گزینه روی یک عدد صحیح بالاتر از3
باعث می شود بزرگترین اندازه زیرنویس نمایش داده شود.captions reload این گزینه داده های زیرنویس بسته را برای ویدئویی که در حال پخش است بارگیری می کند. اگر مقدار گزینه را بازیابی کنید ، مقدار null
خواهد بود. برای بارگیری مجدد داده های زیرنویس بسته ، مقدار را رویtrue
تنظیم کنید.
-
onAutoplayBlocked
- این رویداد هر بار که مرورگر ویژگی های پخش ویدیویی را به صورت جمعی به عنوان "AutoPlay" مسدود می کند ، از آن استفاده می کند. این شامل تلاش برای پخش با هر یک از API های بازیکن زیر است:
- پارامتر
autoplay
- تابع
loadPlaylist
- عملکرد
loadVideoById
- عملکرد
loadVideoByUrl
- عملکرد
playVideo
برای جزئیات کامل ، به خط مشی های خاص مرورگر ( Apple Safari / WebKit ، Google Chrome ، Mozilla Firefox ) و راهنمای خودکار موزیلا مراجعه کنید. - پارامتر
YT.Player
مثال 1: از API با <iframe> موجود استفاده کنید
در این مثال ، یک عنصر
<iframe>
در صفحه قبلاً بازیکنی را که از آن استفاده می شود تعریف می کند. توجه داشته باشید که یا URLsrc
بازیکن باید پارامترenablejsapi
را روی1
تنظیم کند یا ویژگیenablejsapi
عنصر<iframe>
باید رویtrue
تنظیم شود.عملکرد
onPlayerReady
هنگام آماده شدن بازیکن ، رنگ مرز اطراف بازیکن را به نارنجی تغییر می دهد. عملکردonPlayerStateChange
سپس بر اساس وضعیت فعلی پخش کننده ، رنگ مرز اطراف پخش را تغییر می دهد. به عنوان مثال ، وقتی بازیکن بازی می کند ، رنگ سبز است ، هنگام مکث ، آبی هنگام بافر و غیره ، قرمز است.این مثال از کد زیر استفاده می کند:
<iframe id="existing-iframe-example" width="640" height="360" src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1" frameborder="0" style="border: solid 4px #37474F" ></iframe> <script type="text/javascript"> var tag = document.createElement('script'); tag.id = 'iframe-demo'; tag.src = 'https://www.youtube.com/iframe_api'; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); var player; function onYouTubeIframeAPIReady() { player = new YT.Player('existing-iframe-example', { events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } function onPlayerReady(event) { document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00'; } function changeBorderColor(playerStatus) { var color; if (playerStatus == -1) { color = "#37474F"; // unstarted = gray } else if (playerStatus == 0) { color = "#FFFF00"; // ended = yellow } else if (playerStatus == 1) { color = "#33691E"; // playing = green } else if (playerStatus == 2) { color = "#DD2C00"; // paused = red } else if (playerStatus == 3) { color = "#AA00FF"; // buffering = purple } else if (playerStatus == 5) { color = "#FF6DOO"; // video cued = orange } if (color) { document.getElementById('existing-iframe-example').style.borderColor = color; } } function onPlayerStateChange(event) { changeBorderColor(event.data); } </script>
مثال 2: پخش با صدای بلند
این مثال یک پخش کننده ویدیویی 1280px با 720px ایجاد می کند. شنونده رویداد برای رویداد
onReady
سپس با عملکردsetVolume
تماس می گیرد تا حجم را به بالاترین تنظیم تنظیم کند.function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { width: 1280, height: 720, videoId: 'M7lc1UVf-VE', events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); } function onPlayerReady(event) { event.target.setVolume(100); event.target.playVideo(); }
مثال 3: این مثال پارامترهای پخش کننده را تنظیم می کند تا هنگام بارگذاری به طور خودکار ویدیو را پخش کند و کنترل های پخش کننده ویدیو را پنهان کند. همچنین شنوندگان رویداد را برای چندین رویداد که API پخش می کند ، اضافه می کند.
function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { videoId: 'M7lc1UVf-VE', playerVars: { 'autoplay': 1, 'controls': 0 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); }
این مثال از کد زیر استفاده می کند:
<style> .current-values { color: #666; font-size: 12px; } </style> <!-- The player is inserted in the following div element --> <div id="spherical-video-player"></div> <!-- Display spherical property values and enable user to update them. --> <table style="border: 0; width: 640px;"> <tr style="background: #fff;"> <td> <label for="yaw-property">yaw: </label> <input type="text" id="yaw-property" style="width: 80px"><br> <div id="yaw-current-value" class="current-values"> </div> </td> <td> <label for="pitch-property">pitch: </label> <input type="text" id="pitch-property" style="width: 80px"><br> <div id="pitch-current-value" class="current-values"> </div> </td> <td> <label for="roll-property">roll: </label> <input type="text" id="roll-property" style="width: 80px"><br> <div id="roll-current-value" class="current-values"> </div> </td> <td> <label for="fov-property">fov: </label> <input type="text" id="fov-property" style="width: 80px"><br> <div id="fov-current-value" class="current-values"> </div> </td> <td style="vertical-align: bottom;"> <button id="spherical-properties-button">Update properties</button> </td> </tr> </table> <script type="text/javascript"> var tag = document.createElement('script'); tag.id = 'iframe-demo'; tag.src = 'https://www.youtube.com/iframe_api'; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov']; var updateButton = document.getElementById('spherical-properties-button'); // Create the YouTube Player. var ytplayer; function onYouTubeIframeAPIReady() { ytplayer = new YT.Player('spherical-video-player', { height: '360', width: '640', videoId: 'FAtdv94yzp4', }); } // Don't display current spherical settings because there aren't any. function hideCurrentSettings() { for (var p = 0; p < PROPERTIES.length; p++) { document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = ''; } } // Retrieve current spherical property values from the API and display them. function updateSetting() { if (!ytplayer || !ytplayer.getSphericalProperties) { hideCurrentSettings(); } else { let newSettings = ytplayer.getSphericalProperties(); if (Object.keys(newSettings).length === 0) { hideCurrentSettings(); } else { for (var p = 0; p < PROPERTIES.length; p++) { if (newSettings.hasOwnProperty(PROPERTIES[p])) { currentValueNode = document.getElementById(PROPERTIES[p] + '-current-value'); currentValueNode.innerHTML = ('current: ' + newSettings[PROPERTIES[p]].toFixed(4)); } } } } requestAnimationFrame(updateSetting); } updateSetting(); // Call the API to update spherical property values. updateButton. { var sphericalProperties = {}; for (var p = 0; p < PROPERTIES.length; p++) { var propertyInput = document.getElementById(PROPERTIES[p] + '-property'); sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value); } ytplayer.setSphericalProperties(sphericalProperties); } </script>
YouTube Android WebView Media API را گسترش داده است تا بازیکنان رسانه ای تعبیه شده از جمله تعبیه کننده YouTube Player در برنامه های Android را فعال کنند تا صحت برنامه تعبیه را تأیید کنند. با این تغییر ، برنامه ها به طور خودکار یک شناسه برنامه تأیید شده را به YouTube ارسال می کنند. داده های جمع آوری شده از طریق استفاده از این API ، ابرداده برنامه (نام بسته ، شماره نسخه و گواهی امضای) و یک نشانه تأیید دستگاه تولید شده توسط Google Play Services است.
از داده ها برای تأیید یکپارچگی برنامه و دستگاه استفاده می شود. رمزگذاری شده است ، با اشخاص ثالث به اشتراک گذاشته نمی شود و به دنبال یک دوره نگهداری ثابت حذف می شود. توسعه دهندگان برنامه می توانند هویت برنامه خود را در API یکپارچگی رسانه WebView پیکربندی کنند . پیکربندی از یک گزینه امتناع پشتیبانی می کند.