การฉายภาพสื่อ

API android.media.projection ที่เปิดตัวใน Android 5 (ระดับ API 21) ช่วยให้คุณบันทึกเนื้อหาในจอแสดงผลของอุปกรณ์เป็นสตรีมสื่อที่สามารถเล่น บันทึก หรือแคสต์ไปยังอุปกรณ์อื่นๆ เช่น ทีวี ได้

Android 14 (ระดับ API 34) เปิดตัวการแชร์หน้าจอเฉพาะแอป ซึ่งช่วยให้ผู้ใช้แชร์หน้าต่างแอปเดียวแทนหน้าจออุปกรณ์ทั้งหมดได้ ไม่ว่าจะใช้โหมดการจัดหน้าต่างแบบใดก็ตาม การแชร์หน้าจอเฉพาะแอปจะไม่รวมแถบสถานะ แถบการนำทาง การแจ้งเตือน และองค์ประกอบ UI อื่นๆ ของระบบจากการแสดงผลที่แชร์ แม้ว่าจะใช้การแชร์หน้าจอเฉพาะแอปเพื่อจับภาพแอปแบบเต็มหน้าจอก็ตาม ระบบจะแชร์เฉพาะเนื้อหาของแอปที่เลือกเท่านั้น

การแชร์หน้าจอเฉพาะแอปช่วยให้มั่นใจได้ถึงความเป็นส่วนตัวของผู้ใช้ เพิ่มประสิทธิภาพการทำงานของผู้ใช้ และปรับปรุงการทำงานหลายอย่างพร้อมกันโดยให้ผู้ใช้เรียกใช้แอปหลายแอปได้ แต่จำกัดการแชร์เนื้อหาไว้ที่แอปเดียว

การแสดงผล 3 รูปแบบ

การฉายภาพสื่อจะจับภาพเนื้อหาของจอแสดงผลของอุปกรณ์หรือหน้าต่างแอป แล้วฉายภาพที่จับได้ไปยังจอแสดงผลเสมือนจริงที่แสดงผลรูปภาพบน Surface

การแสดงผลของอุปกรณ์จริงที่ฉายลงบนจอแสดงผลเสมือน เนื้อหาของจอแสดงผลเสมือนที่เขียนลงใน `Surface` ที่แอปพลิเคชันจัดเตรียมไว้
รูปที่ 1 หน้าจออุปกรณ์จริงหรือหน้าต่างแอปที่ฉายลงบนจอแสดงผลเสมือนจริง เขียนจอแสดงผลเสมือนไปยัง Surface ที่แอปพลิเคชันจัดเตรียมไว้

แอปพลิเคชันจะแสดง Surface โดยใช้ MediaRecorder, SurfaceTexture หรือ ImageReader ซึ่งจะใช้เนื้อหาของจอแสดงผลที่บันทึกไว้และช่วยให้คุณจัดการรูปภาพที่แสดงผลใน Surface ได้แบบเรียลไทม์ คุณสามารถบันทึกภาพเป็นไฟล์บันทึกหรือแคสต์ไปยังทีวีหรืออุปกรณ์อื่นๆ ได้

จอแสดงผลจริง

เริ่มเซสชันการฉายภาพสื่อโดยรับโทเค็นที่ให้สิทธิ์แอปของคุณในการจับภาพเนื้อหาของจอแสดงผลของอุปกรณ์หรือหน้าต่างแอป โทเค็นจะแสดงโดยอินสแตนซ์ของคลาส MediaProjection

ใช้เมธอด getMediaProjection() ของบริการระบบ MediaProjectionManager เพื่อสร้างอินสแตนซ์ MediaProjection เมื่อคุณเริ่มกิจกรรมใหม่ เริ่มกิจกรรมด้วย Intent จากเมธอด 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 จะระบุมิติข้อมูลของจอแสดงผลเสมือน หากต้องการรับค่าความกว้างและความสูง ให้ใช้ API WindowMetrics ที่เปิดตัวใน Android 11 (ระดับ API 30) (ดูรายละเอียดได้ที่ส่วนขนาดการฉายสื่อ)

พื้นผิว

ปรับขนาดพื้นผิวการฉายภาพสื่อเพื่อสร้างเอาต์พุตในความละเอียดที่เหมาะสม ทำให้พื้นผิวมีขนาดใหญ่ (ความละเอียดต่ำ) สำหรับการแคสต์หน้าจอไปยังทีวีหรือจอคอมพิวเตอร์ และมีขนาดเล็ก (ความละเอียดสูง) สำหรับการบันทึกการแสดงผลของอุปกรณ์

ตั้งแต่ Android 12L (ระดับ API 32) เป็นต้นไป เมื่อแสดงผลเนื้อหาที่บันทึกไว้บนแพลตฟอร์ม ระบบจะปรับขนาดเนื้อหาอย่างสม่ำเสมอโดยคงสัดส่วนภาพไว้ เพื่อให้ขนาดทั้ง 2 ด้านของเนื้อหา (ความกว้างและความสูง) เท่ากับหรือน้อยกว่าขนาดที่สอดคล้องกันของแพลตฟอร์ม จากนั้นเนื้อหาที่บันทึกไว้จะอยู่ตรงกลางของพื้นผิว

วิธีการปรับขนาดของ Android 12L ช่วยปรับปรุงการแคสต์หน้าจอไปยังโทรทัศน์และจอแสดงผลขนาดใหญ่อื่นๆ โดยเพิ่มขนาดของรูปภาพบนแพลตฟอร์มให้สูงสุดขณะที่ยังคงสัดส่วนภาพที่เหมาะสมไว้

สิทธิ์บริการที่ทำงานอยู่เบื้องหน้า

หากแอปกำหนดเป้าหมายเป็น Android 14 ขึ้นไป ไฟล์ Manifest ของแอปต้องมีการประกาศสิทธิ์สำหรับประเภทบริการที่ทำงานอยู่เบื้องหน้า 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()

หากคุณไม่ได้ระบุประเภทบริการที่ทำงานอยู่เบื้องหน้าในการเรียกใช้ ประเภทจะเปลี่ยนเป็นจำนวนเต็มระดับบิตของประเภทบริการที่ทำงานอยู่เบื้องหน้าที่กำหนดไว้ในไฟล์ Manifest โดยค่าเริ่มต้น หากไฟล์ Manifest ไม่ได้ระบุประเภทบริการ ระบบจะแสดงข้อผิดพลาด MissingForegroundServiceTypeException

แอปของคุณต้องขอความยินยอมจากผู้ใช้ก่อนเซสชันการฉายภาพสื่อแต่ละเซสชัน เซสชันคือการเรียกใช้ createVirtualDisplay() 1 ครั้ง ต้องใช้โทเค็น MediaProjection เพียงครั้งเดียวเพื่อโทรออก

ใน Android 14 ขึ้นไป เมธอด createVirtualDisplay() จะแสดง SecurityException หากแอปของคุณทำอย่างใดอย่างหนึ่งต่อไปนี้

  • ส่งผ่านอินสแตนซ์ Intent ที่แสดงผลจาก createScreenCaptureIntent() ไปยัง getMediaProjection() มากกว่า 1 ครั้ง
  • เรียกใช้ createVirtualDisplay() มากกว่า 1 ครั้งในอินสแตนซ์ MediaProjection เดียวกัน

ขนาดการฉายภาพสื่อ

การฉายสื่อสามารถจับภาพจอแสดงผลของอุปกรณ์ทั้งหมดหรือหน้าต่างแอปได้ ไม่ว่าจะอยู่ในโหมดการแสดงหน้าต่างใดก็ตาม

ขนาดเริ่มต้น

เมื่อใช้การฉายภาพสื่อแบบเต็มหน้าจอ แอปของคุณต้องกำหนดขนาดหน้าจอของอุปกรณ์ ในการแชร์หน้าจอเฉพาะแอป แอปของคุณจะไม่สามารถกำหนดขนาดของจอแสดงผลที่จับภาพได้จนกว่าผู้ใช้จะเลือกขอบเขตการจับภาพ ดังนั้น ขนาดเริ่มต้นของการฉายภาพสื่อจึงเป็นขนาดของหน้าจออุปกรณ์

ใช้เมธอด WindowManager getMaximumWindowMetrics() ของแพลตฟอร์มเพื่อแสดงผลออบเจ็กต์ WindowMetrics สำหรับหน้าจออุปกรณ์ แม้ว่าแอปโฮสต์การฉายภาพสื่อจะอยู่ในโหมดหลายหน้าต่าง โดยใช้พื้นที่เพียงบางส่วนของจอแสดงผล

หากต้องการความเข้ากันได้กับ API ระดับ 14 ให้ใช้เมธอด WindowMetricsCalculator computeMaximumWindowMetrics() จากไลบรารี WindowManager ของ Jetpack

เรียกใช้เมธอด WindowMetrics getBounds() เพื่อรับความกว้างและความสูงของจอแสดงผลของอุปกรณ์

การเปลี่ยนแปลงขนาด

ขนาดของการฉายภาพสื่ออาจเปลี่ยนแปลงเมื่อหมุนอุปกรณ์หรือผู้ใช้เลือกหน้าต่างแอปเป็นขอบเขตการจับภาพในการแชร์หน้าจอเฉพาะแอป การฉายภาพสื่ออาจมีแถบสีดำด้านบนและด้านล่างหากเนื้อหาที่บันทึกมีขนาดแตกต่างจากเมตริกหน้าต่างสูงสุดที่ได้รับเมื่อตั้งค่าการฉายภาพสื่อ

หากต้องการตรวจสอบว่าการฉายภาพสื่อสอดคล้องกับขนาดของเนื้อหาที่บันทึกไว้อย่างแม่นยำสำหรับพื้นที่ที่บันทึกไว้และในอุปกรณ์ที่หมุน ให้ใช้ Callback onCapturedContentResize() เพื่อปรับขนาดการบันทึก (ดูข้อมูลเพิ่มเติมได้ในส่วนการปรับแต่งด้านล่าง)

การปรับแต่ง

แอปของคุณสามารถปรับแต่งประสบการณ์ของผู้ใช้ในการฉายภาพสื่อได้ด้วย API MediaProjection.Callback ต่อไปนี้

  • onCapturedContentVisibilityChanged(): ช่วยให้แอปโฮสต์ (แอปที่เริ่มการฉายสื่อ) แสดงหรือซ่อนเนื้อหาที่แชร์ได้

    ใช้ Callback นี้เพื่อปรับแต่ง UI ของแอปตามว่าผู้ใช้มองเห็นขอบเขตที่จับภาพไว้หรือไม่ ตัวอย่างเช่น หากผู้ใช้มองเห็นแอปของคุณและแอปแสดงเนื้อหาที่บันทึกไว้ภายใน UI ของแอป และผู้ใช้มองเห็นแอปที่บันทึกไว้ด้วย (ตามที่ระบุผ่าน Callback นี้) ผู้ใช้จะเห็นเนื้อหาเดียวกัน 2 ครั้ง ใช้ Callback เพื่ออัปเดต UI ของแอปเพื่อซ่อนเนื้อหาที่บันทึกไว้และเพิ่มพื้นที่เลย์เอาต์ในแอปสำหรับเนื้อหาอื่นๆ

  • onCapturedContentResize(): ช่วยให้แอปโฮสต์เปลี่ยนขนาดของการฉายสื่อในจอแสดงผลเสมือนและการฉายสื่อ Surface ตามขนาดของพื้นที่แสดงผลที่จับภาพได้

    ทริกเกอร์เมื่อเนื้อหาที่บันทึก (หน้าต่างแอปเดียวหรือการแสดงผลแบบเต็มหน้าจอของอุปกรณ์) มีการเปลี่ยนแปลงขนาด (เนื่องจากการหมุนอุปกรณ์หรือแอปที่บันทึกเข้าสู่โหมดการแสดงหน้าต่างอื่น) ใช้ API นี้เพื่อปรับขนาดทั้งจอแสดงผลเสมือนและ Surface เพื่อให้สัดส่วนภาพตรงกับเนื้อหาที่จับภาพและไม่แสดงภาพแบบ Letterbox

การกู้คืนทรัพยากร

แอปควรลงทะเบียน Callback MediaProjection onStop() เพื่อรับการแจ้งเตือนเมื่อเซสชันการฉายสื่อหยุดลงและใช้งานไม่ได้ เมื่อเซสชันหยุดลง แอปควรปล่อยทรัพยากรที่แอปถืออยู่ เช่น จอแสดงผลเสมือนและพื้นผิวการฉายภาพ เซสชันการฉายสื่อที่หยุดแล้วจะไม่สามารถสร้างจอแสดงผลเสมือนใหม่ได้อีกต่อไป แม้ว่าแอปของคุณจะไม่ได้สร้างจอแสดงผลเสมือนสำหรับการฉายสื่อนั้นมาก่อนก็ตาม

ระบบจะเรียกใช้ Callback เมื่อการฉายภาพสื่อสิ้นสุดลง การสิ้นสุดนี้อาจเกิดขึ้นได้จากหลายสาเหตุ เช่น

  • ผู้ใช้หยุดเซสชันโดยใช้ UI ของแอปหรือชิปแถบสถานะการฉายสื่อของระบบ
  • หน้าจอกำลังล็อกอยู่
  • เซสชันการฉายภาพสื่ออื่นเริ่มต้นขึ้น
  • กระบวนการของแอปถูกปิด

หากแอปไม่ลงทะเบียน Callback การเรียกใช้ 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 ขึ้นไป ชิปในแถบสถานะที่ใหญ่และเห็นได้ชัดจะแจ้งให้ผู้ใช้ทราบถึงการฉายหน้าจอที่กำลังดำเนินอยู่ ผู้ใช้สามารถแตะชิปเพื่อหยุดไม่ให้แชร์ แคสต์ หรือบันทึกหน้าจอ นอกจากนี้ การฉายหน้าจอจะหยุดโดยอัตโนมัติเมื่อหน้าจออุปกรณ์ล็อกอยู่

รูปที่ 2 ชิปแถบสถานะสำหรับการแชร์หน้าจอ การแคสต์ และการบันทึก

ทดสอบความพร้อมใช้งานของชิปแถบสถานะการฉายสื่อโดยเริ่มการแชร์หน้าจอ การแคสต์ หรือการบันทึก ชิปควรปรากฏในแถบสถานะ

หากต้องการตรวจสอบว่าแอปของคุณปล่อยทรัพยากรและอัปเดต UI เมื่อการฉายภาพหน้าจอหยุดลงเนื่องจากการโต้ตอบของผู้ใช้กับชิปแถบสถานะหรือการเปิดใช้งานหน้าจอล็อก ให้ทำดังนี้

  • สร้างอินสแตนซ์ของ MediaProjection.Callback

  • ใช้เมธอด Callback onStop() ระบบจะเรียกใช้เมธอดเมื่อการฉายภาพหน้าจอหยุดลง ปล่อยทรัพยากรที่แอปของคุณถืออยู่และอัปเดต UI ของแอปตามที่จำเป็น

หากต้องการทดสอบ Callback ให้แตะชิปแถบสถานะหรือล็อกหน้าจออุปกรณ์เพื่อหยุดการฉายภาพหน้าจอ ยืนยันว่ามีการเรียกใช้เมธอด onStop() และแอปตอบสนองตามที่ต้องการ

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับการฉายภาพสื่อได้ที่หัวข้อบันทึกการเล่นวิดีโอและเสียง