Player

یک عنصر رسانه‌ای بومی <r-player> که <video> را با یک نوار کنترل یکپارچه، کشیدن نوار پیشرفت، تنظیم صدا، سرعت پخش، تمام‌صفحه و استریم HLS/DASH/FLV/WebRTC می‌پیچد.

کجا به کار می‌آید: وقتی به پخش‌کننده ویدیویی نیاز دارید که نوار کنترل درون‌ساخت، کشیدن نوار پیشرفت، سرعت پخش، تمام‌صفحه و استریم HLS/DASH/FLV/WebRTC داشته باشد. <r-player> عنصر <video> را می‌پیچد و در هر فریم‌ورکی بی‌تغییر کار می‌کند.

بر پایه وب‌کامپوننت‌ها ساخته شده و hls.js/dashjs/mpegts.js برای قالب مربوط به خودشان به‌هنگام نیاز بار می‌شوند؛ پس همین یک پخش‌کننده در هر فریم‌ورکی بی‌تغییر کار می‌کند. قابلیت‌ها، برگرفته از خودِ سورس:

نوار پیشرفت کشیدنی، با نشانگر بافر و راهنمای زمان هنگام هاور
تنظیم صدا و کلید بی‌صدا
انتخاب سرعت پخش
کلید تمام‌صفحه (و Esc برای خروج)
کلید تصویر-در-تصویر: دکمه تنها وقتی رسم می‌شود که مرورگر واقعاً پشتیبانی کند
دکمه AirPlay / پخش از راه دور: همان انتخابگر دستگاهِ خود مرورگر، با همان شیوه تشخیص قابلیتِ تصویر-در-تصویر
حرکت‌های موبایل: دو ضربه روی نیمه چپ یا راست برای ∓۱۰ ثانیه جابه‌جایی، کشیدن عمودی روی نیمه راست برای صدا (فقط لمسی؛ کار با ماوس و قلم دست‌نخورده می‌ماند)
کشیدن با لمس، قلم یا ماوس: نقطه نوار پیشرفت برای هر سه از یک پیاده‌سازی Pointer Events استفاده می‌کند؛ اگر مرورگر وسط کشیدن اشاره‌گر را پس بگیرد، کشیدن بدون جابه‌جایی تمام می‌شود، چون اشاره‌گر هرگز در موقعیتی که بیننده انتخاب کرده رها نشده است
پیش‌نمایش بندانگشتی هنگام کشیدن: thumbnails را به نشانی مانیفست WebVTTِ اسپرایت‌شیت بدهید تا بالای راهنمای نوار، یک پیش‌نمایش بریده‌شده ظاهر شود
poster / autoplay / loop / muted: اتریبیوت‌های استاندارد <video> که مستقیم پاس داده می‌شوند
زیرنویس: ویژگی tracks را تنظیم کنید؛ رسم زیرنویس‌ها کاملاً بر عهده مرورگر است و یک انتخابگر زبان انتخاب بیننده را به یاد می‌سپارد
خطا و تلاش دوباره: در شکست‌های مرگبار پخش، یک دیالوگ Modal.error()؛ به‌طور پیش‌فرض روشن و با disable-error-modal خاموش‌شدنی
ادامه پخش: با remember-position روشن می‌شود و در localStorage با کلید بر پایه src ذخیره می‌گردد
سنجه‌های QoE: getMetrics() از همان جریان رویدادهای موجود، شمار و مدت وقفه‌های بافر، زمان تا نخستین فریم، شمار تعویض کیفیت و شمار خطاها را بیرون می‌کشد
پخش HLS (.m3u8) و DASH (.mpd) با تعویض خودکار نرخ بیت و انتخابگر دستی کیفیت؛ پخش FLV / MPEG-TS خام (.flv/.ts) با mpegts.js. هر موتور به‌هنگام نیاز بار می‌شود و پیکربندی لازم نیست. اگر پسوند نشانی قابل تشخیص نبود، با اتریبیوت format می‌توانید موتور مشخصی را الزامی کنید (یا به <video src> ساده برگردید).
پخش زنده کم‌تأخیر با WebRTC از راه WHEP (format="webrtc" و src نشانی یک نقطه پایانی WHEP): بدون وابستگی به کتابخانه، چون RTCPeerConnection یک API بومی مرورگر است.
میان‌برهای صفحه‌کلید: Space پخش/مکث، ArrowLeft / ArrowRight جابه‌جایی ۵ ثانیه، Escape خروج از تمام‌صفحه، و روی نوار پیشرفتِ فوکوس‌شده Home/End و کلیدهای جهت

شروع سریع

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

این عنصر به‌صورت display: block رسم می‌شود. عرض و ارتفاع را صریح (با استایل درون‌خطی یا CSS) بدهید تا ویدیو جعبه‌ای برای پر کردن داشته باشد.

مرجع API

ویژگی‌ها

ویژگی	نوع	پیش‌فرض	توضیح
`src`	`string`	`''`	نشانی منبع ویدیو. تغییرش پخش‌کننده را دوباره بار می‌کند. موتور (HLS/بومی) از روی پسوند خودکار تشخیص داده می‌شود.
`format`	`string`	`''`	به‌جای تشخیص از پسوند `src`، موتور مشخصی را الزامی می‌کند (`hls` / `dash` / `flv` / `webrtc` / `native`). برای نشانی‌های استریم بدون پسوند یا امضاشده مفید است و برای `webrtc` الزامی است (نقطه پایانی WHEP پسوندی برای تشخیص ندارد). تغییرش پخش‌کننده را دوباره بار می‌کند.
`volume`	`string`	`''`	صدای آغازین روی مقیاس `0` تا `100`، همان مقیاس `setVolume()`/`getVolume()`.
`currentTime`	`string`	`''`	موقعیت آغازین پخش بر حسب ثانیه. به‌شکل کوچک‌نویس `currenttime` هم پذیرفته می‌شود.
`playbackRate`	`string`	`''`	ضریب سرعت پخش (مثلاً `1`، `1.5`، `2`). به‌شکل کوچک‌نویس `playbackrate` هم پذیرفته می‌شود.
`debug`	`string`	`''`	وقتی مقدارش درست باشد، هر رویداد `change` درونی و هشدارها را در کنسول ثبت می‌کند.
`sheet`	`string`	`''`	متن CSSی که برای استایل سفارشی به Shadow DOM کامپوننت تزریق می‌شود.
`poster`	`string`	`''`	نشانی تصویری که پیش از آغاز پخش نشان داده می‌شود. مستقیم به `<video poster>` می‌رود.
`autoplay`	`boolean`	`false`	اتریبیوت بولی: حضورش یعنی `true`، مثل `<video autoplay>` بومی. مرورگرها معمولاً برای آغاز واقعی پخش خودکار بدون کنش کاربر، `muted` را لازم می‌دانند.
`loop`	`boolean`	`false`	اتریبیوت بولی: در پایان دوباره پخش می‌کند، مثل `<video loop>` بومی.
`muted`	`boolean`	`false`	اتریبیوت بولی: بی‌صدا آغاز می‌شود. در درون، هم صدا را `0` می‌کند (تا آیکن و لغزنده بی‌صدا با هم بخوانند) و هم پرچم بومی `<video>.muted` را می‌گذارد (تا سیاست پخش خودکارِ بی‌صدای مرورگر برآورده شود). برداشتن اتریبیوت، صدای پیشین را برمی‌گرداند.
`thumbnails`	`string`	`''`	نشانی مانیفست WebVTTِ اسپرایت‌شیت؛ بالای راهنمای نوار یک بندانگشتی بریده‌شده نشان می‌دهد. پیش‌نمایش بندانگشتی در پایین را ببینید. مستقل از `src` است: تنها وقتی خودِ این اتریبیوت عوض شود دوباره واکشی می‌شود.
`disable-error-modal`	`boolean`	`false`	دیالوگ درون‌ساخت خطا و تلاش دوباره را خاموش می‌کند. خطاها همچنان از راه رویدادهای `change` با نام `error`/`sourceerror` به شما می‌رسند، پس می‌توانید رابط خودتان را رویش بسازید.
`remember-position`	`boolean`	`false`	ادامه پخش را روشن می‌کند: هنگام مکث و وقتی تب پنهان می‌شود، موقعیت جاری را در `localStorage` (با کلید `src`) ذخیره می‌کند، در بار بعدیِ همان `src` بازمی‌گرداند، و با پایان پخش پاکش می‌کند.
`tracks`	`PlayerTrackConfig[]`	`[]`	مسیرهای زیرنویس. فقط ویژگی JS، بدون اتریبیوت متناظر (پخش‌کننده در هر بار بارگذاری، DOM سبکِ خودش را خالی می‌کند، پس فرزندان `<track>`ی که اعلانی نوشته شوند پیش از اثرگذاری برداشته می‌شوند). زیرنویس در پایین را ببینید.

اتریبیوت‌های زیر نظر (از observedAttributes): src، format، volume، currentTime / currenttime، playbackRate / playbackrate، debug، sheet، poster، thumbnails، autoplay، loop، muted، disable-error-modal، remember-position.

منبع ویدیو `src`

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

پخش زنده WebRTC `format="webrtc"`

html

<r-player format="webrtc" src="https://stream.example.com/whep/room123"></r-player>

برای پخش زنده کم‌تأخیر، format="webrtc" را بگذارید و src را به یک نقطه پایانی WHEP (WebRTC-HTTP Egress Protocol) نشانه بروید؛ همان چیزی که Cloudflare Stream، egress در LiveKit، Millicast و سکوهای مشابه ارائه می‌کنند. وابستگی به کتابخانه‌ای نیست: RTCPeerConnection و fetch APIهای بومی مرورگرند، پس برخلاف HLS/DASH/FLV این موتور تکه‌ای برای دانلود تنبل ندارد. نقطه پایانی WHEP پسوند فایلی برای تشخیص خودکار ندارد، پس format="webrtc" الزامی است و هرگز از src استنتاج نمی‌شود.

زیر پوسته: یک RTCPeerConnection با ترنسیورهای صوت و تصویرِ recvonly می‌سازد، منتظر جمع‌آوری ICE می‌ماند، پیشنهاد SDP را به src POST می‌کند (Content-Type: application/sdp)، پاسخ SDP را از بدنه پاسخ اعمال می‌کند و جریان ورودی را با video.srcObject وصل می‌کند. پایان پخش، منبع نشستی را که سرور در سرایند Location برگردانده DELETE می‌کند. دامنه کار عمداً محدود است: ICE بدون trickle (با سقفی چندثانیه‌ای و سپس ادامه با هر نامزدی که هست) به‌جای سازوکار trickle مبتنی بر PATCH در WHEP، و بدون تحلیل سرایند Link: rel="ice-server" برای راهنمایی‌های STUN/TURN از سمت سرور؛ بیشتر استقرارهای WHEPی که مستقیم در دسترس‌اند بدون هیچ‌کدام از این دو کار می‌کنند. مثل FLV انتخابگر کیفیت هم ندارد: WHEP انتخاب چندنرخیِ استاندارد در سمت کلاینت ندارد، پس در این موتور مقدار qualitySwitchCount در getMetrics() روی 0 می‌ماند.

صدای آغازین `volume`

مقدار روی مقیاس 0 تا 100 است.

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" volume="30"></r-player>

موقعیت آغازین پخش `currentTime`

ثانیه از ابتدای رسانه.

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" currentTime="15"></r-player>

سرعت پخش `playbackRate`

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" playbackRate="1.5"></r-player>

ثبت لاگ اشکال‌زدایی `debug`

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" debug="true"></r-player>

پوستر، پخش خودکار، تکرار، بی‌صدا

html

<r-player
  src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
  poster="/ran/hls/poster.jpg"
  autoplay
  muted
  loop
></r-player>

تصویر-در-تصویر

دکمه PiP در نوار کنترل تنها وقتی پیدا می‌شود که document.pictureInPictureEnabled درست باشد. در مرورگرهایی که پشتیبانی نمی‌کنند دکمه‌ای مرده نمی‌ماند. از راه کد با togglePip() جابه‌جایش کنید.

AirPlay / پخش از راه دور

دکمه ارسال وقتی پیدا می‌شود که مرورگر یا Remote Playback APIِ در مسیر استانداردسازی را عرضه کند (videoElement.remote.prompt() در Chrome/Edge) یا webkitShowPlaybackTargetPicker() در سافاری را (AirPlay)؛ در جاهای دیگر پنهان می‌شود نه غیرفعال، همان قاعده بهبود تدریجیِ تصویر-در-تصویر. انتخابگر دستگاه را از راه کد با showRemotePlaybackPicker() باز کنید.

حرکت‌های موبایل

فقط لمسی، به‌طور پیش‌فرض روشن، و بدون اتریبیوتی برای فعال‌سازی: دو ضربه روی نیمه چپ ویدیو ۱۰ ثانیه به عقب می‌برد، دو ضربه روی نیمه راست ۱۰ ثانیه به جلو (یک نمایش کوتاه -10s/+10s تأییدش می‌کند)، و کشیدن عمودی روی نیمه راست صدا را تنظیم می‌کند. کار با ماوس و قلم به‌کلی دست‌نخورده می‌ماند. یک ضربه ساده هنوز پخش و مکث را جابه‌جا می‌کند، منتها با همان پنجره زمانی‌ای که برای تشخیص دو ضربه به کار می‌رود دیبونس می‌شود؛ پس دو ضربه برای جابه‌جایی هرگز نمی‌گذارد ضربه میانی، پخش را سوسو بدهد. هنگام کشیدن، در کنار رویداد موجود volume، رویداد change با نام gestureseek ({ direction, seconds }) هم فرستاده می‌شود.

پیش‌نمایش بندانگشتی `thumbnails`

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" thumbnails="/ran/hls/thumbnails.vtt"></r-player>

thumbnails به یک مانیفست WebVTT اشاره می‌کند که نشانه‌هایش از همان قرارداد اسپرایت‌شیتِ یوتیوب و Video.js پیروی می‌کنند: متن هر نشانه یک ارجاع تصویری است به‌همراه قطعه #xywh=x,y,w,h که برش آن را از یک اسپرایت‌شیت مشترک مشخص می‌کند:

text

WEBVTT

00:00:00.000 --> 00:00:05.000
sprites.jpg#xywh=0,0,160,90

00:00:05.000 --> 00:00:10.000
sprites.jpg#xywh=160,0,160,90

ارجاع تصویری نسبت به نشانی خودِ فایل VTT حل می‌شود، پس اسپرایت‌شیتی که کنار مانیفست باشد به مسیر مطلق نیاز ندارد. با هاور (یا کشیدن) روی نوار پیشرفت، نشانه‌ای که آن زمان را پوشش می‌دهد به‌شکل بندانگشتی بریده‌شده بالای راهنمای زمان دیده می‌شود؛ وقتی thumbnails تنظیم نشده باشد یا مانیفست هنوز بار نشده باشد، چیزی رسم نمی‌شود. مانیفست به‌ازای هر تغییر thumbnails یک بار واکشی و تحلیل می‌شود و مستقل از src است: عوض کردن کیفیت یا منبع آن را دوباره واکشی نمی‌کند.

زیرنویس `tracks`

const player = document.createElement('r-player');
player.tracks = [
  { src: '/captions/en.vtt', srclang: 'en', label: 'English', default: true },
  { src: '/captions/fr.vtt', srclang: 'fr', label: 'Français' },
];
stage.append(player);

هر ورودی به یک <track> بومی روی <video> زیرین تبدیل می‌شود؛ رسم زیرنویس‌ها یکسره کار خود مرورگر است و پخش‌کننده چیز سفارشی‌ای نمی‌کشد. در نوار کنترل یک انتخابگر زبان (یک <r-select> با همان حس انتخابگر کیفیت) پیدا می‌شود با گزینه Off به‌علاوه یک ورودی برای هر مسیر؛ زبانی که برگزینید در localStorage به یاد می‌ماند و دفعه بعد که هر <r-player>ی در صفحه مسیر بگیرد خودکار اعمال می‌شود (ترجیحی سراسری، نه به ازای هر ویدیو) و اگر هنوز چیزی ذخیره نشده باشد به مسیری با default: true برمی‌گردد. گذاشتن tracks = [] انتخابگر و همه مسیرها را برمی‌دارد. setSubtitleLanguage(lang) زبان فعال را از راه کد تعیین می‌کند (lang یک srclang است، یا 'off').

خطا و تلاش دوباره

به‌طور پیش‌فرض روشن. یک خطای مرگبار در موتور استریم یا رویداد error روی <video> بومی، یک دیالوگ Modal.error() باز می‌کند (با بارگذاری تنبل: تا وقتی چیزی واقعاً شکست نخورد، r-modal اصلاً واکشی نمی‌شود) که دکمه تلاش دوباره دارد و پخش‌کننده را از نو بار می‌کند. برای خاموش کردن این رفتار و مدیریت خطاها به دست خودتان، disable-error-modal را بگذارید و به‌جایش از رویدادهای change با نام error/sourceerror استفاده کنید. خطاهای غیرمرگبار موتور (که hls.js در درون خودش جبرانشان می‌کند) هرگز این دیالوگ را باز نمی‌کنند.

ادامه پخش `remember-position`

html

<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" remember-position></r-player>

هنگام pause و هر وقت تب پنهان شود (visibilitychange، که از beforeunload قابل‌اتکاتر است) مقدار getCurrentTime() را در localStorage (با کلید src) ذخیره می‌کند، در بار بعدیِ همان src بازمی‌گرداند، و وقتی ویدیو به ended رسید پاکش می‌کند. اگر موقعیت ذخیره‌شده تا ۲ ثانیه به پایان مانده باشد بی‌صدا رد می‌شود: ویدیویی که تمام شده باید از نو آغاز شود، نه اینکه از انتهای خودش «ادامه» یابد. تنها موقعیت به یاد می‌ماند؛ ترجیح‌های صدا، سرعت و زیرنویس گزینه‌های جداگانه‌ای‌اند.

سنجه‌های QoE

const player = document.createElement('r-player');
player.addEventListener('change', () => {
  console.log(player.getMetrics());
  // { rebufferCount, rebufferDuration, firstFrameMs, qualitySwitchCount, errorCount }
});
stage.append(player);

getMetrics() یک عکس لحظه‌ایِ شیء ساده برمی‌گرداند که از همان جریان رویدادهای changeی که پایین‌تر مستند شده استخراج می‌شود؛ ردیابی جداگانه‌ای برای روشن کردن وجود ندارد:

میدان	نوع	توضیح
`rebufferCount`	`number`	شمار گذارهای `waiting`→`playing` (گیرهایی که بعد جبران شدند).
`rebufferDuration`	`number`	مجموع زمان (میلی‌ثانیه) گیر افتاده در همه وقفه‌های بافر.
`firstFrameMs`	`number \| null`	میلی‌ثانیه از آغاز بارگذاری `src` جاری تا نخستین فریم قابل پخش؛ تا آن لحظه `null`.
`qualitySwitchCount`	`number`	شمار سطوح کیفیتی که کاربر از انتخابگر برگزیده است.
`errorCount`	`number`	شمار رویدادهای `error`/`sourceerror`.

با بارگذاری هر src/format تازه، این عکس لحظه‌ای صفر می‌شود. همیشه منبع جاری را توصیف می‌کند، نه جمع کل میان منبع‌ها.

متدها

پخش‌کننده روی نمونه عنصر، کنترل‌های دستوری در اختیار می‌گذارد:

متد	توضیح
`play(time?)`	پخش را آغاز می‌کند و در صورت نیاز به `time` (ثانیه) می‌پرد.
`pause()`	پخش را مکث می‌کند.
`getCurrentTime()`	موقعیت جاری پخش بر حسب ثانیه.
`setCurrentTime(seconds)`	به موقعیتی می‌پرد.
`getTotalTime()`	مدت کل رسانه بر حسب ثانیه.
`getVolume()` / `setVolume(v)`	خواندن و تعیین صدا روی مقیاس `0` تا `100`، همان مقیاس اتریبیوت `volume`.
`getPlaybackRate()` / `setPlaybackRate(n)`	خواندن و تعیین ضریب سرعت.
`customRequestFullscreen()`	وارد تمام‌صفحه می‌شود. یک `Promise` برمی‌گرداند.
`customExitFullscreen()`	از تمام‌صفحه بیرون می‌آید. یک `Promise` برمی‌گرداند.
`togglePip()`	به تصویر-در-تصویر وارد یا از آن خارج می‌شود. اگر پشتیبانی نباشد یا منبعی بار نشده باشد کاری نمی‌کند.
`setSubtitleLanguage(lang)`	مسیر زیرنویس فعال را با `srclang` تعیین می‌کند، یا با `'off'` خاموشش می‌کند.
`getMetrics()`	عکس لحظه‌ای جاری سنجه‌های QoE را می‌خواند.
`showRemotePlaybackPicker()`	انتخابگر دستگاه AirPlay / پخش از راه دورِ مرورگر را باز می‌کند. اگر پشتیبانی نباشد یا منبعی بار نشده باشد کاری نمی‌کند.

رویدادها

پخش‌کننده تنها یک CustomEvent با نام change می‌فرستد. هر گذار وضعیت درونی (رویدادهای رسانه‌ای بومی و کنش‌های رابط خودِ پخش‌کننده) از همان می‌گذرد، پس یک بار مشترک می‌شوید و بر پایه detail.type شاخه می‌زنید.

html

<r-player id="player" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

<script>
  const player = document.getElementById('player');
  player.addEventListener('change', (e) => {
    const { type, data, currentTime, duration, tag } = e.detail;
    console.log(type, currentTime, duration);
    // `tag` خودِ نمونه <r-player> است
  });
</script>

بار `detail`

ویژگی	نوع	توضیح
`type`	`string`	نام تغییری که رخ داده است.
`data`	`unknown`	مقدار یا رویداد همراه آن تغییر.
`currentTime`	`number`	زمان جاری پخش (ثانیه).
`duration`	`number`	مدت کل رسانه (ثانیه).
`tag`	`Element`	نمونه `<r-player>`.

مقادیر `detail.type`

وضعیت‌های رسانه‌ای بومی که از <video> زیرین پاس داده می‌شوند:

نوع	توضیح
`canplay`	داده به‌قدر کافی برای آغاز پخش رسیده است.
`canplaythrough`	می‌تواند بدون وقفه بافر تا پایان پخش شود.
`complete`	رسم به پایان رسید.
`durationchange`	مقدار `duration` تغییر کرد.
`emptied`	رسانه خالی یا دوباره بار شد.
`ended`	پخش به پایان رسید.
`error`	خطای رسانه‌ای رخ داد (اگر `disable-error-modal` نباشد، دیالوگ درون‌ساخت خطا و تلاش دوباره را هم باز می‌کند).
`loadstart`	مرورگر بارگذاری رسانه را آغاز کرد.
`loadedmetadata`	فراداده بار شد.
`loadeddata`	نخستین فریم بار شد.
`progress`	در حین بارگذاری منبع، هر چند وقت یک بار فرستاده می‌شود.
`ratechange`	سرعت پخش تغییر کرد.
`seeking`	جابه‌جایی آغاز شد.
`seeked`	جابه‌جایی تمام شد.
`stalled`	مرورگر می‌کوشد داده بگیرد اما چیزی نمی‌رسد.
`suspend`	بارگذاری رسانه معلق شد.
`timeupdate`	`currentTime` تغییر کرد.
`volumechange`	صدای عنصر ویدیو تغییر کرد.
`waiting`	پخش در انتظار داده متوقف شد.
`play`	پخش آغاز شد.
`playing`	پخش پس از بافر یا مکث از سر گرفته شد.
`pause`	پخش مکث شد.

کنش‌های ویژه پخش‌کننده:

نوع	`data`	توضیح
`volume`	`number` (`0`–`100`)	صدا از راه نوار کنترل یا کلید بی‌صدا تغییر کرد.
`speed`	`number`	سرعت پخش از راه انتخابگر سرعت تغییر کرد.
`fullscreen`	`boolean`	وارد تمام‌صفحه شد (`true`) یا از آن بیرون آمد (`false`).
`pictureinpicture`	`boolean`	وارد تصویر-در-تصویر شد (`true`) یا از آن بیرون آمد (`false`)؛ چه با `togglePip()` و چه با کنترل‌های پنجره PiP خود مرورگر.
`subtitlechange`	`string`	زبان زیرنویس از راه انتخابگر CC یا `setSubtitleLanguage()` عوض شد: یک `srclang` یا `'off'`.
`resume`	`number`	موقعیتی ذخیره‌شده هنگام بارگذاری بی‌صدا بازگردانده شد (`remember-position`)؛ `data` همان زمان بازگردانده‌شده بر حسب ثانیه است.
`levelsready`	`{ levels }`	مانیفست موتور استریم تحلیل شد؛ سطوح کیفیت اکنون در دسترس‌اند.
`sourceerror`	`{ fatal, detail }`	خطای موتور استریم رخ داد (به `src` خام برمی‌گردد؛ خطای مرگبار در نبود `disable-error-modal` دیالوگ خطا و تلاش دوباره را هم باز می‌کند؛ خطاهای غیرمرگبار جبران درونی خود موتورند و بازش نمی‌کنند).
`qualityswitch`	`{ level }`	کاربر از انتخابگر، سطحی از کیفیت را برگزید.
`gestureseek`	`{ direction, seconds }`	حرکت دو ضربه برای جابه‌جایی رخ داد (`direction` برابر `'forward'`/`'backward'`).

اسلات‌ها

این پخش‌کننده محتوای اسلات نمی‌پذیرد: در سازنده و دوباره در هر بار بارگذاری منبع، فرزندان DOM سبک خودش را خالی می‌کند (this.innerHTML = ''). برای لایه‌های سفارشی، به‌جایش با اتریبیوت sheet به پخش‌کننده استایل بدهید.

استایل‌دهی

<r-player> ۱۳۶ ویژگی سفارشی CSS از آنِ خود دارد، به‌علاوه توکن‌های معنایی که از پوسته می‌خواند. هر جا که ارث برسد می‌توانید یکی را تعیین کنید: :root، یک دربرگیرنده، یا خود عنصر:

css

r-player {
  --ran-player-tip-background: var(--ran-color-bg-subtle);
}

فهرست کامل در توکن‌های استایل است؛ اینکه سراغ کدام توکن بروید کار سیستم طراحی است.

بهترین شیوه‌ها

اندازه: میزبان display: block است و اندازه ذاتی ندارد؛ همیشه عرض و ارتفاع صریح بدهید وگرنه ویدیو جمع می‌شود.
موتورهای استریم: منبع‌های .m3u8 (HLS)، .mpd (DASH) و .flv/.ts (FLV/MPEG-TS از راه mpegts.js) هرکدام موتور خود را به‌هنگام نیاز و خودکار بار می‌کنند؛ پیکربندی لازم نیست. اگر پسوند نشانی قابل تشخیص نبود (نشانی‌های CDN بدون پسوند یا امضاشده)، به‌جای تکیه بر تشخیص، اتریبیوت format را صریح بگذارید (مثلاً format="dash"). WebRTC (format="webrtc") همیشه صریح است: در نقطه پایانی WHEP چیزی برای تشخیص نیست.
یک شنونده: به‌جای وصل کردن هندلرهای فراوان، یک شنونده change با switch (detail.type) را ترجیح دهید؛ همه وضعیت‌ها از change می‌گذرند.
واحد صدا: volume (اتریبیوت)، setVolume()/getVolume() و بار تغییر volume همگی از یک مقیاس واحد 0 تا 100 استفاده می‌کنند. تنها <video>.volume بومیِ زیرین است که 0 تا 1 است، و پخش‌کننده در همان یک مرز تبدیل می‌کند.
تصویر-در-تصویر بهبود تدریجی است: وقتی مرورگر پشتیبانی نکند، دکمه پنهان می‌شود نه غیرفعال؛ تکیه نکنید که همیشه در DOM هست.
استایل سفارشی: برای تزریق CSS به Shadow DOM از اتریبیوت sheet استفاده کنید؛ خودِ پخش‌کننده دستگیره ::part() صادرشده‌ای ندارد.

نقشه راه

<r-player> در حال توسعه فعال است؛ برای دیدن برنامه‌های بعدی، PLAYER_ROADMAP.md در مخزن را ببینید.

Player ​

شروع سریع ​

مرجع API ​

ویژگی‌ها ​

منبع ویدیو src ​

پخش زنده WebRTC format="webrtc" ​

صدای آغازین volume ​

موقعیت آغازین پخش currentTime ​

سرعت پخش playbackRate ​

ثبت لاگ اشکال‌زدایی debug ​

پوستر، پخش خودکار، تکرار، بی‌صدا ​

تصویر-در-تصویر ​

AirPlay / پخش از راه دور ​

حرکت‌های موبایل ​

پیش‌نمایش بندانگشتی thumbnails ​

زیرنویس tracks ​

خطا و تلاش دوباره ​

ادامه پخش remember-position ​

سنجه‌های QoE ​

متدها ​

رویدادها ​

بار detail ​

مقادیر detail.type ​

اسلات‌ها ​

استایل‌دهی ​

بهترین شیوه‌ها ​

نقشه راه ​

Player

شروع سریع

مرجع API

ویژگی‌ها

منبع ویدیو `src`

پخش زنده WebRTC `format="webrtc"`

صدای آغازین `volume`

موقعیت آغازین پخش `currentTime`

سرعت پخش `playbackRate`

ثبت لاگ اشکال‌زدایی `debug`

پوستر، پخش خودکار، تکرار، بی‌صدا

تصویر-در-تصویر

AirPlay / پخش از راه دور

حرکت‌های موبایل

پیش‌نمایش بندانگشتی `thumbnails`

زیرنویس `tracks`

خطا و تلاش دوباره

ادامه پخش `remember-position`

سنجه‌های QoE

متدها

رویدادها

بار `detail`

مقادیر `detail.type`

اسلات‌ها

استایل‌دهی

بهترین شیوه‌ها

نقشه راه