نمایش جریانی رسانه

android.media.projection APIهای معرفی‌شده در Android 5 (سطح API 21) به شما امکان می‌دهند محتوای نمایشگر دستگاه را به‌عنوان یک جریان رسانه‌ای ضبط کنید که می‌توانید آن را پخش کنید، ضبط کنید، یا به دستگاه‌های دیگر مانند تلویزیون‌ها ارسال کنید.

Android 14 (سطح API‏ ۳۴) هم‌رسانی صفحه برنامه را معرفی می‌کند که به کاربران امکان می‌دهد یک پنجره برنامه را به‌جای کل صفحه دستگاه، صرف‌نظر از حالت پنجره‌ای، هم‌رسانی کنند. هم‌رسانی صفحه برنامه، نوار وضعیت، نوار پیمایش، اعلان‌ها، و دیگر عناصر میانای کاربر سیستم را از نمایشگر هم‌رسانی‌شده مستثنی می‌کند—حتی وقتی از هم‌رسانی صفحه برنامه برای ضبط برنامه در حالت تمام‌صفحه استفاده می‌شود. فقط محتوای برنامه انتخاب‌شده هم‌رسانی می‌شود.

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

سه نمایشگر

پروجکشن رسانه محتوای نمایشگر دستگاه یا پنجره برنامه را ضبط می‌کند و سپس تصویر ضبط‌شده را به نمایشگر مجازی که تصویر را در Surface رندر می‌کند، ارسال می‌کند.

نمایشگر دستگاه واقعی روی نمایشگر مجازی فرافکنی شده است. محتوای
              نمایشگر مجازی در «سطح» ارائه‌شده توسط برنامه نوشته شده است.
شکل ۱. صفحه دستگاه واقعی یا پنجره برنامه روی نمایشگر مجازی پروجکت شده است. نمایشگر مجازی در Surface ارائه‌شده توسط برنامه نوشته شده است.

برنامه Surface را ازطریق MediaRecorder، SurfaceTexture، یا ImageReader ارائه می‌دهد که محتوای نمایشگر ضبط‌شده را مصرف می‌کند و به شما امکان می‌دهد تصاویر پردازش‌شده در Surface را به‌طور هم‌زمان مدیریت کنید. می‌توانید تصاویر را به‌صورت ضبط‌شده ذخیره کنید یا آن‌ها را به تلویزیون یا دستگاه دیگری ارسال کنید.

نمایشگر واقعی

با دریافت کردن نشانه‌ای که به برنامه شما توانایی ضبط محتوای نمایشگر دستگاه یا پنجره برنامه را می‌دهد، جلسه نمایش جریانی رسانه را شروع کنید. نمونه‌ای از کلاس MediaProjection نشان‌دهنده این کد است.

از روش getMediaProjection() سرویس سیستم MediaProjectionManager برای ایجاد نمونه MediaProjection هنگام شروع فعالیت جدید استفاده کنید. فعالیت را با هدفی از روش createScreenCaptureIntent() شروع کنید تا عملیات ضبط صفحه‌نمایش را مشخص کنید:

val mediaProjectionManager = getSystemService(MediaProjectionManager::class.java)
var mediaProjection: MediaProjection?

val startMediaProjection = registerForActivityResult(
    StartActivityForResult()
) { result ->
    if (result.resultCode == RESULT_OK) {
        result.data?.let { data ->
            mediaProjection = mediaProjectionManager
                .getMediaProjection(result.resultCode, data)
        }
    }
}

startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())

نمایشگر مجازی

بخش اصلی فرافکنی رسانه، نمایشگر مجازی است که با فراخوانی createVirtualDisplay() در نمونه MediaProjection ایجاد می‌کنید:

virtualDisplay = mediaProjection.createVirtualDisplay(
    "ScreenCapture",
    width,
    height,
    screenDensity,
    DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
    surface,
    null, null
)

پارامترهای width و height ابعاد نمایشگر مجازی را مشخص می‌کنند. برای به‌دست آوردن مقادیر عرض و ارتفاع، از میاناهای برنامه‌سازی کاربردی WindowMetrics معرفی‌شده در Android 11 (سطح میانای برنامه‌سازی کاربردی ۳۰) استفاده کنید. (برای جزئیات، به بخش اندازه پخش رسانه مراجعه کنید.)

سطح

سطح نمایش جریانی رسانه را طوری اندازه کنید که خروجی با وضوح مناسب تولید شود. برای پخش محتوای صفحه‌نمایش در تلویزیون یا مانیتور رایانه، سطح را بزرگ (وضوح کم) و برای ضبط نمایشگر دستگاه، سطح را کوچک (وضوح بالا) کنید.

از Android 12L (سطح میانای برنامه‌سازی کاربردی ۳۲) به‌بعد، هنگام ارائه محتوای ضبط‌شده در سطح، سیستم محتوا را به‌طور یکنواخت مقیاس‌بندی می‌کند و نسبت ابعادی را حفظ می‌کند، به‌طوری‌که هر دو بعد محتوا (عرض و ارتفاع) برابر یا کمتر از ابعاد مربوطه سطح باشد. سپس محتوای ضبط‌شده در مرکز سطح قرار می‌گیرد.

رویکرد مقیاس‌بندی Android 12L پخش محتوای صفحه‌نمایش در تلویزیون‌ها و دیگر نمایشگرهای بزرگ را با به‌حداکثر رساندن اندازه تصویر سطح و درعین‌حال اطمینان از نسبت ابعادی مناسب بهبود می‌بخشد.

اجازه سرویس پیش‌زمینه‌ای

اگر برنامه شما Android 14 یا بالاتر را هدف قرار می‌دهد، مانیفست برنامه باید شامل اعلامیه اجازه برای نوع سرویس پیش‌زمینه‌ای mediaProjection باشد:

<manifest ...>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
    <application ...>
        <service
            android:name=".MyMediaProjectionService"
            android:foregroundServiceType="mediaProjection"
            android:exported="false">
        </service>
    </application>
</manifest>

سرویس ارسال محتوا را با تماس با startForeground() شروع کنید.

اگر نوع سرویس پیش‌زمینه‌ای را در فراخوان مشخص نکنید، نوع به‌طور پیش‌فرض به عدد صحیح بیتی از انواع سرویس پیش‌زمینه‌ای تعریف‌شده در مانیفست تبدیل می‌شود. اگر مانیفست هیچ نوع سرویسی را مشخص نکند، سیستم MissingForegroundServiceTypeException را صادر می‌کند.

برنامه شما باید قبل‌از هر جلسه پخش رسانه، رضایت کاربر را درخواست کند. جلسه یک تماس تکی با createVirtualDisplay() است. از هر کد MediaProjection فقط یک‌بار باید برای برقراری تماس استفاده شود.

در Android 14 یا بالاتر، اگر برنامه‌تان یکی از کارهای زیر را انجام دهد، روش createVirtualDisplay() SecurityException را برمی‌گرداند:

  • نمونه Intent برگردانده‌شده از createScreenCaptureIntent() را بیش‌از یک بار به getMediaProjection() ارسال می‌کند
  • بیش‌از یک بار در یک MediaProjection تماس می‌گیردcreateVirtualDisplay() نمونه

اندازه نمایش جریانی رسانه

فرافکنی رسانه می‌تواند کل نمایشگر دستگاه یا پنجره برنامه را صرف‌نظر از حالت پنجره‌بندی ضبط کند.

اندازه اولیه

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

از روش پلاتفرم WindowManager getMaximumWindowMetrics() برای برگرداندن شیء WindowMetrics برای صفحه‌نمایش دستگاه استفاده کنید، حتی اگر برنامه میزبان پخش رسانه در حالت چندپنجره‌ای باشد و فقط بخشی از نمایشگر را اشغال کند.

برای سازگاری تا سطح میانای برنامه‌سازی کاربردی ۱۴، از روش WindowMetricsCalculator computeMaximumWindowMetrics() از کتابخانه Jetpack WindowManager استفاده کنید.

برای دریافت عرض و ارتفاع نمایشگر دستگاه، روش WindowMetrics getBounds() را فراخوانی کنید.

تغییرات اندازه

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

برای اطمینان از اینکه نمایش رسانه دقیقاً با اندازه محتوای ضبط‌شده برای هر منطقه ضبط‌شده و در سراسر چرخش‌های دستگاه مطابقت دارد، از فراخوانی برگشتی onCapturedContentResize() برای تغییر اندازه ضبط استفاده کنید. (برای اطلاعات بیشتر، به بخش سفارشی‌سازی در زیر مراجعه کنید).

سفارشی‌سازی

برنامه شما می‌تواند تجربه کاربری پخش رسانه را با میاناهای برنامه‌سازی کاربردی MediaProjection.Callback زیر سفارشی‌سازی کند:

  • onCapturedContentVisibilityChanged(): به برنامه میزبان (برنامه‌ای که پخش رسانه را شروع کرده است) امکان می‌دهد محتوای هم‌رسانی‌شده را نشان دهد یا پنهان کند.

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

  • onCapturedContentResize(): به برنامه میزبان امکان می‌دهد اندازه نمایش جریانی رسانه را در نمایشگر مجازی و نمایش جریانی رسانه Surface براساس اندازه منطقه نمایش ضبط‌شده تغییر دهد.

    هرگاه اندازه محتوای ضبط‌شده (یک پنجره برنامه یا کل نمایشگر دستگاه) تغییر کند (به‌دلیل چرخش دستگاه یا ورود برنامه ضبط‌شده به حالت پنجره‌ای متفاوت)، راه‌اندازی می‌شود. از این API برای تغییر اندازه نمایشگر مجازی و سطح استفاده کنید تا مطمئن شوید نسبت ابعادی با محتوای ضبط‌شده مطابقت دارد و ضبط به‌صورت جعبه‌ای نیست.

بازیابی منابع

برنامه شما باید MediaProjection onStop() را ثبت کند تا وقتی جلسه پخش رسانه متوقف و نامعتبر می‌شود، مطلع شود. وقتی جلسه متوقف می‌شود، برنامه‌تان باید منابعی را که دراختیار دارد، مثل نمایشگر مجازی و سطح پخش، آزاد کند. جلسه پخش رسانه متوقف‌شده دیگر نمی‌تواند نمایشگر مجازی جدیدی ایجاد کند، حتی اگر برنامه‌تان قبلاً نمایشگر مجازی برای آن پخش رسانه ایجاد نکرده باشد.

وقتی پخش رسانه خاتمه می‌یابد، سیستم فراخوانی برگشتی را فراخوانی می‌کند. این بستن حساب می‌تواند به دلایل مختلفی اتفاق بیفتد، ازجمله:

  • کاربر جلسه را بااستفاده از میانای کاربر برنامه یا تراشه نوار وضعیت پخش رسانه سیستم متوقف کند
  • صفحه درحال قفل شدن است
  • جلسه نمایش جریانی رسانه دیگری شروع شود
  • پردازش برنامه متوقف شود

اگر برنامه‌تان تماس برگشتی را ثبت نکند، هر تماسی با createVirtualDisplay() IllegalStateException را برمی‌گرداند.

انصراف

Android 14 یا بالاتر هم‌رسانی صفحه برنامه را به‌طور پیش‌فرض فعال می‌کند. هر جلسه نمایش رسانه به کاربران این امکان را می‌دهد که پنجره برنامه یا کل نمایشگر را هم‌رسانی کنند.

برنامه شما می‌تواند با فراخوانی روش createScreenCaptureIntent(MediaProjectionConfig) با آرگومان MediaProjectionConfig که از فراخوانی createConfigForDefaultDisplay() برگردانده شده است، از هم‌رسانی صفحه برنامه انصراف دهد.

تماس با createScreenCaptureIntent(MediaProjectionConfig) با آرگومان MediaProjectionConfig که از تماس با createConfigForUserChoice() برگردانده شده است، مانند رفتار پیش‌فرض است، یعنی تماس با createScreenCaptureIntent().

برنامه‌های قابل‌تغییر اندازه

همیشه برنامه‌های پخش رسانه را قابل‌تغییر اندازه کنید (resizeableActivity="true"). برنامه‌های قابل‌تغییر اندازه از تغییرات پیکربندی دستگاه و حالت چندپنجره‌ای پشتیبانی می‌کنند (پشتیبانی از حالت چندپنجره‌ای را ببینید).

اگر برنامه‌تان قابل‌تغییر اندازه نیست، باید حدود نمایش را از بافت پنجره پُرسمان کند و از getMaximumWindowMetrics() برای بازیابی WindowMetrics حداکثر فضای نمایش دردسترس برنامه استفاده کند :

val windowContext = context.createWindowContext(
    context.display,
    WindowManager.LayoutParams.TYPE_APPLICATION, null
)
val projectionMetrics = windowContext.getSystemService(WindowManager::class.java)
    .maximumWindowMetrics

تراشه نوار وضعیت و توقف خودکار

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

برای برنامه‌هایی که روی دستگاه‌های دارای Android 15 QPR1 یا بالاتر اجرا می‌شوند، یک تراشه نوار وضعیت که بزرگ و برجسته است، به کاربران هشدار می‌دهد که هر گونه نمایش صفحه نمایش در حال پیشرفت را نشان دهند. کاربران می‌توانند روی تراشه ضربه بزنند تا از اشتراک‌گذاری، پخش یا ضبط صفحه نمایش خود جلوگیری کنند. همچنین، با قفل شدن صفحه نمایش دستگاه، نمایش صفحه به طور خودکار متوقف می شود.

شکل ۲. تراشه نوار وضعیت برای هم‌رسانی صفحه‌نمایش، ارسال محتوا، و ضبط کردن.

با شروع هم‌رسانی صفحه‌نمایش، ارسال محتوا، یا ضبط، دردسترس بودن تراشه نوار وضعیت طرح‌افکنی رسانه را آزمایش کنید. تراشه باید در نوار وضعیت نشان داده شود.

برای اطمینان از اینکه برنامه‌تان منابع را آزاد می‌کند و میانای کاربر خود را هنگام توقف پخش محتوای صفحه‌نمایش به‌دلیل تعامل کاربر با تراشه نوار وضعیت یا فعال شدن صفحه قفل به‌روز می‌کند، موارد زیر را انجام دهید:

  • نمونه‌ای از MediaProjection.Callback ایجاد کنید.

  • روش فراخوانی onStop() را پیاده‌سازی کنید. این روش زمانی فراخوانی می‌شود که پخش محتوای صفحه‌نمایش متوقف شود. هر منبعی را که برنامه‌تان نگه داشته است آزاد کنید و میانای کاربر برنامه را درصورت نیاز به‌روز کنید.

برای آزمایش کردن تماس برگشتی، روی تراشه نوار وضعیت تک‌ضرب بزنید یا صفحه‌نمایش دستگاه را قفل کنید تا پخش محتوای صفحه‌نمایش متوقف شود. تأیید کنید که روش onStop() فراخوانی می‌شود و برنامه‌تان به‌درستی پاسخ می‌دهد.

منابع بیشتر

برای اطلاعات بیشتر درباره پخش رسانه، به ضبط ویدیو و بازپخش صدا مراجعه کنید.