API android.media.projection ที่เปิดตัวใน Android 5 (ระดับ API 21) ช่วยให้คุณบันทึกเนื้อหาในจอแสดงผลของอุปกรณ์เป็นสตรีมสื่อที่สามารถเล่น บันทึก หรือแคสต์ไปยังอุปกรณ์อื่นๆ เช่น ทีวี ได้
Android 14 (ระดับ API 34) เปิดตัวการแชร์หน้าจอเฉพาะแอป ซึ่งช่วยให้ผู้ใช้แชร์หน้าต่างแอปเดียวแทนหน้าจออุปกรณ์ทั้งหมดได้ ไม่ว่าจะใช้โหมดการจัดหน้าต่างแบบใดก็ตาม การแชร์หน้าจอเฉพาะแอปจะไม่รวมแถบสถานะ แถบการนำทาง การแจ้งเตือน และองค์ประกอบ UI อื่นๆ ของระบบจากการแสดงผลที่แชร์ แม้ว่าจะใช้การแชร์หน้าจอเฉพาะแอปเพื่อจับภาพแอปแบบเต็มหน้าจอก็ตาม ระบบจะแชร์เฉพาะเนื้อหาของแอปที่เลือกเท่านั้น
การแชร์หน้าจอเฉพาะแอปช่วยให้มั่นใจได้ถึงความเป็นส่วนตัวของผู้ใช้ เพิ่มประสิทธิภาพการทำงานของผู้ใช้ และปรับปรุงการทำงานหลายอย่างพร้อมกันโดยให้ผู้ใช้เรียกใช้แอปหลายแอปได้ แต่จำกัดการแชร์เนื้อหาไว้ที่แอปเดียว
การแสดงผล 3 รูปแบบ
การฉายภาพสื่อจะจับภาพเนื้อหาของจอแสดงผลของอุปกรณ์หรือหน้าต่างแอป แล้วฉายภาพที่จับได้ไปยังจอแสดงผลเสมือนจริงที่แสดงผลรูปภาพบน Surface
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 ขึ้นไป ชิปในแถบสถานะที่ใหญ่และเห็นได้ชัดจะแจ้งให้ผู้ใช้ทราบถึงการฉายหน้าจอที่กำลังดำเนินอยู่ ผู้ใช้สามารถแตะชิปเพื่อหยุดไม่ให้แชร์ แคสต์ หรือบันทึกหน้าจอ นอกจากนี้ การฉายหน้าจอจะหยุดโดยอัตโนมัติเมื่อหน้าจออุปกรณ์ล็อกอยู่
ทดสอบความพร้อมใช้งานของชิปแถบสถานะการฉายสื่อโดยเริ่มการแชร์หน้าจอ การแคสต์ หรือการบันทึก ชิปควรปรากฏในแถบสถานะ
หากต้องการตรวจสอบว่าแอปของคุณปล่อยทรัพยากรและอัปเดต UI เมื่อการฉายภาพหน้าจอหยุดลงเนื่องจากการโต้ตอบของผู้ใช้กับชิปแถบสถานะหรือการเปิดใช้งานหน้าจอล็อก ให้ทำดังนี้
สร้างอินสแตนซ์ของ
MediaProjection.Callbackใช้เมธอด Callback
onStop()ระบบจะเรียกใช้เมธอดเมื่อการฉายภาพหน้าจอหยุดลง ปล่อยทรัพยากรที่แอปของคุณถืออยู่และอัปเดต UI ของแอปตามที่จำเป็น
หากต้องการทดสอบ Callback ให้แตะชิปแถบสถานะหรือล็อกหน้าจออุปกรณ์เพื่อหยุดการฉายภาพหน้าจอ ยืนยันว่ามีการเรียกใช้เมธอด onStop() และแอปตอบสนองตามที่ต้องการ
แหล่งข้อมูลเพิ่มเติม
ดูข้อมูลเพิ่มเติมเกี่ยวกับการฉายภาพสื่อได้ที่หัวข้อบันทึกการเล่นวิดีโอและเสียง