تعریف ترکیبی از آیتم‌های رسانه‌ای

کتابخانه Media3 Transformer مجموعه‌ای از ابزارها را برای ویرایش و دستکاری رسانه‌ها ارائه می‌دهد. یکی از اجزای اصلی برای ویرایش چندرسانه‌ای، رابط برنامه‌نویسی کاربردی (API) Composition API) است. این API به شما امکان می‌دهد چندین آیتم رسانه ورودی، مانند کلیپ‌های ویدیویی، تصاویر و آهنگ‌های صوتی را در یک ساختار واحد و منسجم مرتب کنید که سپس می‌توان آن را پردازش، پیش‌نمایش یا خروجی گرفت. یک Composition می‌توان به عنوان یک جدول زمانی در نظر گرفت که یک یا چند توالی از رسانه‌ها را در خود جای می‌دهد. هر توالی (که توسط EditedMediaItemSequence تعریف می‌شود) شامل آیتم‌های رسانه‌ای جداگانه (که به عنوان نمونه‌های EditedMediaItem تعریف می‌شوند) است. تبدیل‌ها و جلوه‌ها را می‌توان به یک EditedMediaItem جداگانه یا به کل یک Composition اعمال کرد.

یک Composition نقطه ورود شما برای موارد استفاده متنوع با Media3 Transformer است، مانند:

• ترکیب متوالی فایل‌های صوتی، تصویری و ویدیویی.
• قرار دادن یک ویدیو روی ویدیوی دیگر (تصویر در تصویر).
• میکس کردن یک آهنگ صوتی پس زمینه با یک سکانس ویدیویی.
• اعمال جلوه‌های بصری یا صوتی در کل یک قطعه ویرایش‌شده.
• مدیریت سناریوهای پیچیده مانند پردازش ویدیوی HDR.

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

مفاهیم و کلاس‌های کلیدی

برای استفاده‌ی مؤثر از API Composition ، درک کلاس‌های اصلی دخیل در ساخت یک کامپوزیشن رسانه‌ای مهم است:

Effects :

• هدف: یک شیء Effects مجموعه‌ای از پردازنده‌های صوتی و جلوه‌های ویدیویی است.
• نحوه استفاده: در زمینه یک Composition ، می‌توان Effects روی نمونه‌های EditedMediaItem به صورت جداگانه تنظیم کرد تا کلیپ‌های خاص یا روی کل Composition (معمولاً برای افکت‌های Presentation که بر خروجی نهایی تأثیر می‌گذارند، مانند تنظیم وضوح تصویر یا نرخ فریم) تغییر دهند.
• دلیل اهمیت: Effects مکانیزمی برای اعمال تبدیل‌ها، فیلترها و سایر پردازش‌ها به رسانه شما، هم در سطح آیتم‌های منفرد و هم در سطح ترکیب کلی هستند. برای اطلاعات بیشتر، به Transformations مراجعه کنید.

EditedMediaItem :

• هدف: این کلاس نشان‌دهنده‌ی یک قطعه‌ی رسانه‌ای واحد (مانند یک ویدیو، تصویر یا فایل صوتی) و ویرایش‌هایی است که باید روی آن اعمال شود.
• نحوه استفاده: یک EditedMediaItem یک MediaItem (که به محتوای واقعی رسانه اشاره می‌کند) را با یک شیء Effects گروه‌بندی می‌کند.
• دلیل اهمیت: این بخش، بلوک سازنده‌ی اساسی ترکیب‌بندی شماست. به شما این امکان را می‌دهد که قبل از ترکیب هر قطعه با قطعات دیگر در یک توالی، دقیقاً مشخص کنید که کدام رسانه‌ها را در آن بگنجانید و هر قطعه چگونه به نظر برسد و چه صدایی داشته باشد.

EditedMediaItemSequence :

• هدف: نشان‌دهنده‌ی یک توالی خطی از اشیاء EditedMediaItem است که قرار است یکی پس از دیگری پخش شوند.
• نحوه استفاده: یک EditedMediaItemSequence با فهرستی از اشیاء EditedMediaItem ساخته می‌شود. هر سکانس درون یک Composition مشابه یک تراک یا لایه در یک جدول زمانی ویرایش ویدیوی چند تراکی است. به عنوان مثال، یک سکانس ممکن است شامل کلیپ‌های ویدیویی اصلی شما باشد، در حالی که سکانس دیگری که از نظر زمانی همپوشانی دارد، ممکن است شامل کلیپ‌های ویدیویی باشد که روی اولی قرار می‌گیرند، و سکانس دیگری ممکن است فقط شامل یک تراک صوتی برای موسیقی پس‌زمینه باشد.
• دلیل اهمیت: یک EditedMediaItemSequence آیتم‌های رسانه‌ای مرتبط را که باید مستقیماً پس از یکدیگر قرار گیرند، گروه‌بندی می‌کند. با استفاده از چندین توالی، می‌توانید ترتیب‌های پیچیده‌تری مانند لایه‌بندی صدا یا ایجاد پوشش‌های بصری ایجاد کنید.

Composition :

• هدف: این شیء سطح بالا است که کل جدول زمانی رسانه‌ای که باید پردازش شود را نشان می‌دهد. این شیء به عنوان ظرفی برای تمام توالی‌های رسانه‌ای و هرگونه تنظیمات یا جلوه‌های جهانی که بر کل خروجی اعمال می‌شود، عمل می‌کند.
• نحوه استفاده: یک Composition شامل یک یا چند شیء EditedMediaItemSequence است. همچنین می‌توانید جلوه‌های سراسری کامپوزیشن را اعمال کنید و پیکربندی‌های سراسری مانند حالت HDR را مستقیماً روی Composition تنظیم کنید. اگر یک Composition شامل چندین شیء EditedMediaItemSequence باشد، این توالی‌ها می‌توانند طوری تنظیم شوند که به صورت متوالی پخش شوند یا می‌توانند در زمان همپوشانی داشته باشند، که امکان طرح‌بندی‌های همپوشانی مانند تصویر در تصویر یا انتقال از یک سکانس به سکانس دیگر را فراهم می‌کند.
• دلیل اهمیت: یک Composition ساختار کلی رسانه ورودی که باید پردازش شود را تعریف می‌کند و یک شیء رایج است که می‌توانید از آن هم برای پیش‌نمایش ویرایش‌ها با CompositionPlayer و هم برای خروجی گرفتن از یک ویدیوی خروجی با ویرایش‌های اعمال شده با استفاده از Transformer استفاده کنید.

ایجاد و اکسپورت یک Composition

در اینجا مثالی از ایجاد یک فایل ویدیویی که شامل دو کلیپ ویدیویی ویرایش شده، یک آهنگ صوتی روی آن قرار گرفته و خروجی گرفتن از آن آمده است:

val video1 = EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build()

val video2 = EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build()

val videoSequence = EditedMediaItemSequence.withAudioAndVideoFrom(listOf(video1, video2))

val backgroundAudio = EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build()

val backgroundAudioSequence =
  EditedMediaItemSequence.withAudioFrom(listOf(backgroundAudio))
    .buildUpon()
    .setIsLooping(true) // Loop audio track through duration of videoSequence
    .build()

val composition = Composition.Builder(videoSequence, backgroundAudioSequence).build()

transformer.start(composition, filePath)
Composition.kt

EditedMediaItem video1 = new EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build();

EditedMediaItem video2 = new EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build();

EditedMediaItemSequence videoSequence =
    EditedMediaItemSequence.withAudioAndVideoFrom(ImmutableList.of(video1, video2));

EditedMediaItem backgroundAudio =
    new EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build();

EditedMediaItemSequence backgroundAudioSequence =
    EditedMediaItemSequence.withAudioFrom(ImmutableList.of(backgroundAudio))
        .buildUpon()
        .setIsLooping(true) // Loop audio track through duration of videoSequence
        .build();

Composition composition =
    new Composition.Builder(videoSequence, backgroundAudioSequence).build();

transformer.start(composition, filePath);
CompositionJava.java

نمونه‌هایی از موارد استفاده پشتیبانی‌شده

این یک لیست غیر جامع از موارد استفاده‌ای است که Transformer API با Composition پشتیبانی می‌کند:

• ترکیب متوالی فایل‌های صوتی، تصویری و ویدیویی.
• اضافه کردن صدای پس‌زمینه به یک فایل ویدیویی
• افزودن جلوه‌ها به یک ترکیب‌بندی
• نگاشت تُن ورودی HDR به SDR برای تولید خروجی SDR با کیفیت بصری بهتر.

محدودیت‌های فعلی

توالی‌های درون یک کامپوزیشن باید شرایط ذکر شده در Transformer.start() را داشته باشند. علاوه بر این، عملیات زیر هنوز هنگام کار با کامپوزیشن‌ها پشتیبانی نمی‌شوند:

• محو شدن متقاطع آهنگ‌های ویدیویی یا صوتی

درخواست‌های ویژگی

اگر درخواست هرگونه ویژگی برای APIهای Transformer دارید، مشکل خود را در مخزن گیت‌هاب Media3 ثبت کنید.