अलग-अलग साइज़, डाइमेंशन या कॉन्फ़िगरेशन वाले डिवाइसों के लिए मीडिया कॉन्टेंट को स्केल करना

Android, पोर्ट्रेट मोड वाले स्मार्टफ़ोन के अलावा, कई अन्य डिवाइसों पर भी काम करता है. जैसे, फ़ोल्ड किए जा सकने वाले डिवाइस, टैबलेट, डेस्कटॉप विंडोइंग एनवायरमेंट, और बाहरी डिसप्ले. अगर आपको लगता है कि स्क्रीन की ज्यामिति स्टैटिक है, तो हो सकता है कि मीडिया कॉन्टेंट स्ट्रेच हो जाए, क्रॉप हो जाए या अनजाने में लेटरबॉक्स हो जाए. आपके ऐप्लिकेशन को अलग-अलग डिसप्ले मोड में, सोर्स मीडिया के अलग-अलग आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) के हिसाब से डाइनैमिक तौर पर अडजस्ट होना चाहिए. जैसे, क्लासिक 4:3 से लेकर अल्ट्रा-वाइड तक.

Jetpack Compose में ज़्यादातर मीडिया लेआउट से जुड़ी गड़बड़ियां, आर्किटेक्चर से जुड़ी इन तीन सामान्य समस्याओं की वजह से होती हैं:

  • विंडो इनसेट हैंडलिंग और एज-टू-एज कोलिज़न में अंतर.
  • विंडो के साइज़ का गलत हिसाब लगाने की वजह से, लेआउट के अपडेट एक जैसे नहीं होते.
  • कॉन्टेंट को स्केल करने के विकल्पों को गलत तरीके से कॉन्फ़िगर किया गया है.

इस गाइड में, Media3 और Jetpack Compose का इस्तेमाल करके, इन सभी समस्याओं को हल करने की रणनीतियां और सबसे सही तरीके बताए गए हैं.

विंडो इनसेट और एज-टू-एज डिसप्ले के बीच होने वाले टकराव को मैनेज करना

Android 15 (एपीआई लेवल 35) और इसके बाद के वर्शन वाले डिवाइसों पर, एपीआई लेवल 35 या इसके बाद के वर्शन को टारगेट करने वाले ऐप्लिकेशन, डिफ़ॉल्ट रूप से एज-टू-एज दिखते हैं. स्टेटस बार, नेविगेशन बार, और डेस्कटॉप कैप्शन बार जैसे सिस्टम बार, आपके ऐप्लिकेशन के कॉन्टेंट के ऊपर दिखते हैं. साथ ही, डिसप्ले कटआउट की वजह से कॉन्टेंट के कुछ हिस्से छिप सकते हैं.

विंडो इनसेट को सही तरीके से मैनेज न करने पर, लेआउट से जुड़ी दो मुख्य समस्याएं आती हैं:

  • सिस्टम बार ओवरलैप: वीडियो फ़्रेम, सबटाइटल, और प्लेबैक कंट्रोल, स्टेटस बार (घड़ी, बैटरी आइकॉन), जेस्चर या नेविगेशन बार या डिसप्ले कटआउट (कैमरा नॉच) की वजह से कुछ हद तक छिप जाते हैं. सेटअप करने से जुड़े सामान्य दिशा-निर्देशों के लिए, एज-टू-एज सेट अप करना लेख पढ़ें.
  • डेस्कटॉप मोड में कैप्शन बार से जुड़ी समस्या: डेस्कटॉप विंडोइंग मोड में, सिस्टम विंडो को मैनेज करने के लिए सबसे ऊपर एक कैप्शन बार दिखाता है. स्टैंडर्ड लेआउट, कस्टम हेडर या एज-टू-एज मीडिया कैनवस को रेंडर करते हैं. हालांकि, इनमें कैप्शन बार को ध्यान में नहीं रखा जाता. इस वजह से, वीडियो फ़्रेम और सबसे ऊपर मौजूद प्लेबैक कंट्रोल छिप जाते हैं और उन पर क्लिक नहीं किया जा सकता. विंडो की स्थितियों के बारे में ज़्यादा जानने के लिए, डेस्कटॉप विंडोइंग की सुविधा के साथ काम करने वाले ऐप्लिकेशन बनाना लेख पढ़ें.
सिस्टम स्टेटस बार, एज-टू-एज मीडिया कैनवस और प्लेबैक कंट्रोल को ओवरलैप कर रहा है. जेस्चर वाला नेविगेशन बार, एज-टू-एज मीडिया कैनवस को ओवरलैप कर रहा है. डेस्कटॉप पर कैप्शन बार, वीडियो के सबसे ऊपर मौजूद प्लेबैक कंट्रोल को ओवरलैप कर रहा है.
पहली इमेज. सिस्टम स्टेटस बार, जेस्चर वाला नेविगेशन बार, और डेस्कटॉप कैप्शन बार, एज-टू-एज मीडिया कैनवस को ओवरलैप करते हैं. साथ ही, वीडियो कॉन्टेंट और प्लेबैक कंट्रोल को छिपाते हैं.

इनसेट मैनेजमेंट की रणनीतियां

आपका ऐप्लिकेशन, सिस्टम इनसेट के हिसाब से डाइनैमिक तौर पर अडजस्ट होना चाहिए. यह इस बात पर निर्भर करता है कि प्लेयर, इमर्सिव मोड में है या नॉन-इमर्सिव मोड में.

नॉन-इमर्सिव कॉन्फ़िगरेशन

नॉन-इमर्सिव प्लेबैक में, सिस्टम बार दिखते रहते हैं, ताकि डिवाइस का कॉन्टेक्स्ट बना रहे.

जब प्लेयर विंडो के किनारों तक फैल जाए, तो हर PlayerDefaults कंट्रोल बार के उन किनारों पर WindowInsets.safeDrawing और only के साथ windowInsetsPadding लागू करें जहां वह सिस्टम बार या डिसप्ले कटआउट से मिलता है. उदाहरण के लिए, TopControls पर Top + Horizontal और BottomControls पर Bottom + Horizontal. इससे कंट्रोल, सिस्टम बार से दूर रहते हैं. हालांकि, वीडियो का प्लैटफ़ॉर्म कंटेनर में फैला रहता है.

@Composable
fun NonImmersiveVideoPlayer(
  player: Player,
  showControls: Boolean,
  modifier: Modifier = Modifier,
) {
  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the status bar, caption bar, and display cutout
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(WindowInsetsSides.Top + WindowInsetsSides.Horizontal)
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the navigation bar and display cutout
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(
                WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal
              )
            ),
      )
    },
  )
}

नॉन-इमर्सिव मोड में, ऐप्लिकेशन विंडो इनसेट पैडिंग को इंटिग्रेट करता है, ताकि कॉन्टेंट को डाइनैमिक तरीके से अंदर की ओर शिफ़्ट किया जा सके.
दूसरी इमेज. नॉन-इमर्सिव मोड में, ऐप्लिकेशन विंडो इनसेट पैडिंग लागू करता है, ताकि कंट्रोल को अंदर की ओर शिफ़्ट किया जा सके.

इमर्सिव कॉन्फ़िगरेशन (पोर्ट्रेट और लैंडस्केप)

फ़ुल-स्क्रीन इमर्सिव मोड में, कैनवस को बड़ा करके वीडियो देखने का शानदार अनुभव दिया जाता है. साथ ही, प्लेबैक कंट्रोल को ऐक्सेस करने की सुविधा भी दी जाती है:

  1. मीडिया कंट्रोल ओवरले (जैसे, सबसे ऊपर और सबसे नीचे मौजूद कंट्रोल) पर windowInsetsPadding लागू करें, ताकि वे डिसप्ले कटआउट या सिस्टम जेस्चर वाले हिस्सों को ओवरलैप न करें. उदाहरण के लिए, सबसे नीचे मौजूद कंट्रोल पर WindowInsets.displayCutout को WindowInsets.systemGestures के साथ जोड़ें, ताकि सीक बार, किनारे से स्वाइप करने वाले जेस्चर के साथ ओवरलैप न हो.
  2. DisposableEffect में WindowInsetsControllerCompat का इस्तेमाल करके, सिस्टम बार छिपाएं. इससे यह पक्का किया जा सकेगा कि कंपोज़ेबल से बाहर निकलने पर, सिस्टम यूज़र इंटरफ़ेस (यूआई) की विज़िबिलिटी पहले जैसी हो जाए.

@Composable
fun ImmersiveVideoPlayer(player: Player, showControls: Boolean, modifier: Modifier = Modifier) {
  val view = LocalView.current

  // Manages the system UI lifecycle to create an edge-to-edge cinematic experience
  DisposableEffect(view) {
    // Finds the hosting Activity, unwrapping any ContextWrapper around the view's context
    val activity =
      generateSequence(view.context) { (it as? ContextWrapper)?.baseContext }
        .filterIsInstance<Activity>()
        .firstOrNull()
    val window = activity?.window ?: return@DisposableEffect onDispose {}
    val controller = WindowCompat.getInsetsController(window, view)

    // Records the current system bar state so it can be restored on dispose
    val insets = ViewCompat.getRootWindowInsets(view)
    val wereSystemBarsVisible =
      insets == null ||
        insets.isVisible(WindowInsetsCompat.Type.statusBars()) ||
        insets.isVisible(WindowInsetsCompat.Type.navigationBars())
    val previousBehavior = controller.systemBarsBehavior

    // Hides status bars, navigation bars, and caption bars to maximize the video canvas
    controller.hide(WindowInsetsCompat.Type.systemBars())

    // Allows hidden system bars to temporarily reappear with a swipe gesture from the edge
    controller.systemBarsBehavior =
      WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

    onDispose {
      // Restores the previous system bar state when leaving the composable
      controller.systemBarsBehavior = previousBehavior
      if (wereSystemBarsVisible) {
        controller.show(WindowInsetsCompat.Type.systemBars())
      }
    }
  }

  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the display cutout while the system bars are hidden
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout.only(
                WindowInsetsSides.Top + WindowInsetsSides.Horizontal
              )
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the display cutout and system gesture areas
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout
                .union(WindowInsets.systemGestures)
                .only(WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal)
            ),
      )
    },
  )
}

वीडियो प्लेयर के इमर्सिव मोड में जाने पर, सिस्टम बार अपने-आप छिप जाता है. इससे फ़ुल-स्क्रीन पर सिनमैटिक अनुभव मिलता है.
तीसरी इमेज. वीडियो प्लेयर के इमर्सिव मोड में जाने पर, सिस्टम बार छिप जाते हैं.

डाइनैमिक विंडो के साइज़ और लेआउट के अपडेट का हिसाब लगाना

ऐप्लिकेशन के स्टार्टअप पर, स्क्रीन की चौड़ाई या ऊंचाई का हिसाब सिर्फ़ एक बार लगाने से, डिवाइस कॉन्फ़िगरेशन में बदलाव होने पर लेआउट पुरानी वैल्यू पर निर्भर हो जाते हैं. जैसे, फ़ोल्ड किए जा सकने वाले डिवाइस को अनफ़ोल्ड करने, मल्टी-विंडो सेशन का साइज़ बदलने या डिसप्ले को घुमाने पर.

ऐसे मामलों में, भले ही कोई चाइल्ड कॉम्पोनेंट Modifier.fillMaxWidth() का सही तरीके से इस्तेमाल करता हो, लेकिन अगर उसके पैरंट कंटेनर में पुराने डाइमेंशन इस्तेमाल किए गए हैं, तो वह अडैप्ट नहीं हो पाएगा. इससे लेआउट स्ट्रेच हो सकता है, क्लिप हो सकता है या रिस्पॉन्सिव नहीं हो सकता.

यहां दिए गए उदाहरण में, बाईं ओर मौजूद फ़्रेम में स्टैंडर्ड व्यूपोर्ट पर सही रेंडरिंग दिखाई गई है. वहीं, दाईं ओर मौजूद फ़्रेम में दिखाया गया है कि डिवाइस को अनफ़ोल्ड करने पर, विंडो के पुराने डाइमेंशन के हिसाब से कॉन्टेंट अडजस्ट नहीं हो पाता. इस वजह से, कॉन्टेंट का लेआउट रिस्पॉन्सिव नहीं रहता.

डाइनैमिक आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) के हिसाब से, स्टैंडर्ड व्यूपोर्ट पर सही रेंडरिंग. डिवाइस को अनफ़ोल्ड करने पर, विंडो के पुराने डाइमेंशन अडजस्ट न होना.
चौथी इमेज. डाइनैमिक आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) के अडैप्टेशन की तुलना.

लेआउट की पुरानी सीमाओं से बचने के लिए, Jetpack Media Query API का इस्तेमाल करें. यह एपीआई, एक्सपेरिमेंट के तौर पर उपलब्ध है और डिफ़ॉल्ट रूप से बंद रहता है. इसलिए, सबसे पहले ComposeUiFlags.isMediaQueryIntegrationEnabled = true को सेट करके, mediaQuery फ़ंक्शन को चालू करें. उदाहरण के लिए, setContent को कॉल करने से पहले ऐसा करें. इसके बाद, @OptIn(ExperimentalMediaQueryApi::class) की मदद से शामिल हों.

derivedMediaQuery का इस्तेमाल करके, मौजूदा विंडो के साइज़ की शर्तों का आकलन करें. जैसे, windowWidth. इससे विंडो में बदलाव होने पर, आपका लेआउट अपडेट हो जाता है. इसके लिए, आपको बेवजह फिर से कॉम्पोज़ करने की ज़रूरत नहीं पड़ती. derivedMediaQuery को WindowSizeClass ब्रेकपॉइंट के साथ जोड़ा जा सकता है, ताकि विंडो के बड़ा होने पर सिंगल-पेन और मल्टी-पेन प्लेयर लेआउट के बीच स्विच किया जा सके:

@OptIn(ExperimentalMediaQueryApi::class)
@Composable
fun AdaptiveVideoPlayerScreen(
  player: Player,
  modifier: Modifier = Modifier,
  relatedContent: @Composable () -> Unit,
) {
  val isWideWindow by derivedMediaQuery {
    windowWidth >= WindowSizeClass.WIDTH_DP_MEDIUM_LOWER_BOUND.dp
  }

  if (isWideWindow) {
    // Medium or expanded width: place the player alongside a details or playlist pane
    Row(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.weight(0.65f).fillMaxHeight())
      Box(modifier = Modifier.weight(0.35f).fillMaxHeight()) { relatedContent() }
    }
  } else {
    // Compact width: stack a 16:9 player above the details pane
    Column(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.fillMaxWidth().aspectRatio(16f / 9f))
      Box(modifier = Modifier.weight(1f).fillMaxWidth()) { relatedContent() }
    }
  }
}

कॉन्टेंट की स्केलिंग और आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) कॉन्फ़िगर करना

उपलब्ध कंटेनर एरिया को मैनेज करने और मीडिया कॉन्टेंट को स्केल करने के बीच अंतर करना. सिस्टम बार और डिसप्ले कटआउट के हिसाब से कंटेनर की सीमाएं सेट करने के लिए, इनसेट मैनेजमेंट का इस्तेमाल करें. जैसे, सेफ़ एरिया पैडिंग. इसके बाद, उन सीमाओं के अंदर स्केलिंग रणनीतियां लागू करें. कंटेनर को स्ट्रक्चर करने और अलग-अलग आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) के हिसाब से विज़ुअल कॉन्टेंट को स्केल करने के लिए, डिज़ाइन से जुड़े दिशा-निर्देश देखें. इसके लिए, कॉन्टेंट का कंपोज़िशन और स्ट्रक्चर पर जाएं.

यहां दिए गए उदाहरण में, बाईं ओर मौजूद इमेज से पता चलता है कि क्रॉप करने की रणनीति से, कॉन्टेंट को कैसे काटा जा सकता है. ऐसा तब होता है, जब कॉन्टेंट को पूरी तरह से दिखाना ज़रूरी हो. वहीं, दाईं ओर मौजूद इमेज से पता चलता है कि फ़िट करने की रणनीति से, फ़ुल-फ़्रेम रेंडरिंग के लिए नेटिव आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) को कैसे बनाए रखा जाता है.

क्रॉप करने की रणनीति की वजह से, कॉन्टेंट का अहम हिस्सा कट जाता है. हालांकि, कॉन्टेंट को पूरा दिखाना ज़रूरी होता है. फ़ुल-फ़्रेम रेंडरिंग के लिए, नेटिव आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) बनाए रखने की रणनीति.
पांचवीं इमेज. स्केलिंग के व्यवहार की तुलना.

Media3 के कॉम्पोनेंट, वीडियो के स्टैंडर्ड आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) को अपने-आप मैनेज करते हैं. हालांकि, कस्टम Compose लेआउट या सीमित कंटेनर (जैसे, स्क्रोल किए जा सकने वाले सोशल फ़ीड) के साथ काम करते समय, साफ़ तौर पर ContentScale कॉन्फ़िगरेशन करना ज़रूरी हो जाता है. कॉन्टेंट का गलत स्केल चुनने से, लेआउट से जुड़ी समस्याएं हो सकती हैं. जैसे, वीडियो का खराब होना (स्ट्रेच होना) या अनचाहा लेटरबॉक्सिंग, जिससे व्यूपोर्ट में खाली जगह रह जाती है. इन विकल्पों के बिना वीडियो सरफ़ेस को मैन्युअल तरीके से मैनेज करने पर, स्क्रीन को रोटेट करने या फ़ोल्ड किए जा सकने वाले डिवाइस की स्थिति में बदलाव करने पर, लेआउट खराब हो सकते हैं.

चाहे 16:9 वीडियो को 4:3 स्क्रीन पर दिखाया जा रहा हो या 4:3 वीडियो को 16:9 डिसप्ले पर, Player कंपोज़ेबल, डिफ़ॉल्ट रूप से ContentScale.Fit पर सेट होता है. इससे पूरा वीडियो दिखता है और लेटरबॉक्सिंग या पिलरबॉक्सिंग लागू करके, वीडियो को क्लिप नहीं किया जाता.

डिसप्ले मोड में बाद में किए जाने वाले बदलाव (जैसे, ज़ूम करना या काटना) उपयोगकर्ता के हिसाब से होने चाहिए. उदाहरण के लिए, कंटेनर को पूरी तरह से भरने के लिए, ContentScale.Crop पर स्विच करें. इंटरैक्टिव स्केलिंग टॉगल, लेआउट की ज़रूरी शर्तों को उपयोगकर्ता के लिए उपलब्ध विकल्पों के साथ बैलेंस करता है.

लागू करने के तरीके के सैंपल

स्टैंडर्ड Compose ContentScale प्रॉपर्टी का इस्तेमाल करके, फ़ुल फ़्रेम विज़िबिलिटी लागू की जा सकती है और आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) मैनेज किया जा सकता है.

Player कंपोज़ेबल का इस्तेमाल करना

सबसे आसान और सीधा तरीका है, Player कंपोज़ेबल का इस्तेमाल करना. यह एक हाई-लेवल रैपर के तौर पर काम करता है, जो स्केलिंग की सीमाओं को अपने-आप मैनेज करता है. यह वीडियो रेंडरिंग के लिए ContentFrame को पसंद के मुताबिक बनाए जा सकने वाले कंट्रोल ओवरले (topControls, centerControls, bottomControls) और शटर लेयर के साथ जोड़ता है:

@Composable
fun FitVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier.fillMaxSize(), // Fill the available space
    contentScale = ContentScale.Fit, // Default; shown for clarity
  )
}

कस्टम वीडियो प्लेयर लेआउट बनाते समय या वीडियो स्ट्रीम पर सीधे कस्टम यूज़र इंटरफ़ेस (यूआई) लेयर डालते समय, सटीक और लोअर-लेवल लेआउट कंट्रोल के लिए, सीधे ContentFrame का इस्तेमाल किया जा सकता है.

उपयोगकर्ता के कंट्रोल वाली डाइनैमिक स्केलिंग के लिए टॉगल बटन

अपने ऐप्लिकेशन में कॉन्टेंट देखने का अनुभव बेहतर बनाने के लिए, कॉन्टेंट को अलग-अलग साइज़ में दिखाने के विकल्पों के बीच स्विच करने के लिए, एक वैकल्पिक टॉगल जोड़ा जा सकता है. दो बार टैप करने के जेस्चर का पता लगाकर, प्लेयर की स्थिति को ContentScale.Fit और ContentScale.Crop के बीच तुरंत टॉगल किया जा सकता है. इस सुविधा को और बेहतर बनाया जा सकता है, ताकि यह पिंच-टू-ज़ूम या अन्य मल्टी-टच जेस्चर का इस्तेमाल करके, डाइनैमिक तौर पर ContentScale अडजस्टमेंट कर सके. यह सुविधा, वीडियो स्ट्रीमिंग वाले आधुनिक ऐप्लिकेशन की तरह काम करती है.

छठी इमेज.
ContentScale.Fit और ContentScale.Crop के बीच स्विच करना.

@Composable
fun ZoomableVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  var isCropped by rememberSaveable { mutableStateOf(false) }

  Player(
    player = player,
    modifier =
      modifier
        .fillMaxSize()
        // Handle double-tap to toggle between Fit and Crop scaling
        .pointerInput(Unit) { detectTapGestures(onDoubleTap = { isCropped = !isCropped }) },
    contentScale = if (isCropped) ContentScale.Crop else ContentScale.Fit,
  )
}

कॉन्टेंट को स्केल करने के कई विकल्प मौजूद हैं. अपने इस्तेमाल के हिसाब से स्केलिंग का विकल्प चुनें: कम अवधि के वीडियो या स्क्रोल किए जा सकने वाले फ़ीड के लिए, ContentScale.Crop का इस्तेमाल करें. इनमें स्क्रीन को भरना मुख्य लक्ष्य होता है. वहीं, ज़रूरी मार्जिन जानकारी वाले मीडिया के लिए, डिफ़ॉल्ट रूप से ContentScale.Fit का इस्तेमाल करें. जैसे, खेल-कूद के स्कोर या सबटाइटल, ताकि ज़रूरी विज़ुअल कॉन्टेक्स्ट को सुरक्षित रखा जा सके.