إنشاء تطبيق أساسي لتعديل الفيديوهات باستخدام Media3 Transformer

تم تصميم واجهات برمجة التطبيقات Transformer في Jetpack Media3 لتعديل الوسائط. أداءً وموثوقًا به. يدعم المحول عددًا من العمليات، بما في ذلك:

• تعديل فيديو من خلال قطع الفيديو وتغيير حجمه وتدويره
• إضافة تأثيرات مثل العناصر المركّبة والفلاتر
• معالجة تنسيقات خاصة، مثل النطاق العالي الديناميكية (HDR) والفيديوهات بالتصوير البطيء
• تصدير ملف وسائط بعد تطبيق التعديلات

وتُطلعك هذه الصفحة على بعض حالات الاستخدام الرئيسية التي تتناولها المحوِّل. لمزيد من التفاصيل، يمكنك التوجه إلى الأدلّة الكاملة حول تحويل Media3:

البدء

للبدء، أضِف تبعية على وحدات "المحول" و"التأثير" و"الشائعة". في Jetpack Media3:

implementation "androidx.media3:media3-transformer:1.4.1"
implementation "androidx.media3:media3-effect:1.4.1"
implementation "androidx.media3:media3-common:1.4.1"

تأكَّد من استبدال 1.4.1 بالإصدار الذي تفضّله من المكتبة. يمكنك الرجوع إلى ملاحظات الإصدار لرؤية أحدث إصدار.

صفوف مهمة

ضبط الناتج

باستخدام Transformer.Builder، يمكنك الآن تحديد videoMimeType audioMimetype عن طريق تعيين الدالة دون الحاجة إلى إنشاء الكائن TransformationRequest.

تحويل الترميز بين التنسيقات

يوضّح الرمز التالي كيفية ضبط عنصر Transformer على إخراج فيديو H.265/AVC وصوت AAC:

val transformer = Transformer.Builder(context)
    .setVideoMimeType(MimeTypes.VIDEO_H265)
    .setAudioMimeType(MimeTypes.AUDIO_AAC)
    .build()

Transformer transformer = new Transformer.Builder(context)
    .setVideoMimeType(MimeTypes.VIDEO_H265)
    .setAudioMimeType(MimeTypes.AUDIO_AAC)
    .build();

إذا كان تنسيق وسائط الإدخال مطابقًا لطلب تحويل الصوت أو فيديو، يتحول المحوّل تلقائيًا إلى التحويل، وهو نسخ العينات المضغوطة من حاوية الإدخال إلى حاوية الإخراج بدون التعديل. وهذا يتجنب التكلفة الحاسوبية وفقدان الجودة المحتمل فك الترميز وإعادة تشفيره بالتنسيق ذاته.

ضبط وضع النطاق العالي الديناميكية

إذا كان ملف وسائط الإدخال بتنسيق HDR، يمكنك الاختيار بين بضعة الأوضاع المختلفة لكيفية معالجة تطبيق Transformer لمعلومات النطاق العالي الديناميكية (HDR). ربما تريد استخدام HDR_MODE_KEEP_HDR أو HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL

على الأجهزة المتوافقة مع إمكانات الترميز المطلوبة والتي تعمل بنظام التشغيل Android 13 (المستوى 33 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث، تتيح لك عناصر Transformer تعديل فيديوهات HDR. HDR_MODE_KEEP_HDR هو الوضع التلقائي عند إنشاء الكائن Composition، كما هو موضح في التعليمة البرمجية التالية:

val composition = Composition.Builder(
    ImmutableList.of(videoSequence))
    .setHdrMode(HDR_MODE_KEEP_HDR)
    .build()

Composition composition = new Composition.Builder(
    ImmutableList.of(videoSequence))
    .setHdrMode(Composition.HDR_MODE_KEEP_HDR)
    .build();

إعداد ملف وسائط

تمثل العلامة MediaItem محتوى صوتيًا أو عنصر فيديو في تطبيقك تجمع EditedMediaItem MediaItem معًا. مع التحولات لتطبيقها عليه.

قطع فيديو

لإزالة الأجزاء غير المرغوب فيها من الفيديو، يمكنك ضبط بداية ونهاية مخصّصتين. المواضع عن طريق إضافة ClippingConfiguration إلى MediaItem.

val clippingConfiguration = MediaItem.ClippingConfiguration.Builder()
    .setStartPositionMs(10_000) // start at 10 seconds
    .setEndPositionMs(20_000) // end at 20 seconds
    .build()
val mediaItem = MediaItem.Builder()
    .setUri(videoUri)
    .setClippingConfiguration(clippingConfiguration)
    .build()

ClippingConfiguration clippingConfiguration = new MediaItem.ClippingConfiguration.Builder()
    .setStartPositionMs(10_000) // start at 10 seconds
    .setEndPositionMs(20_000) // end at 20 seconds
    .build();
MediaItem mediaItem = new MediaItem.Builder()
    .setUri(videoUri)
    .setClippingConfiguration(clippingConfiguration)
    .build();

استخدام التأثيرات المضمنة

تتضمن Media3 عددًا من تأثيرات الفيديو المدمجة لإجراء التحويلات الشائعة، على سبيل المثال:

بالنسبة إلى التأثيرات الصوتية، يمكنك إضافة سلسلة AudioProcessor تعمل على تحويل البيانات الصوتية الأولية (PCM). على سبيل المثال، يمكنك استخدام ChannelMixingAudioProcessor لمزج القنوات الصوتية وتوسيع نطاقها.

ولاستخدام هذه التأثيرات، يمكنك إنشاء مثيل للتأثير أو معالج الصوت مثيل لـ Effects مع تأثيرات الصوت والفيديو التي تريد تطبيقها عليها عنصر الوسائط، ثم إضافة كائن Effects إلى EditedMediaItem.

val channelMixingProcessor = ChannelMixingAudioProcessor()
val rotateEffect = ScaleAndRotateTransformation.Builder().setRotationDegrees(60f).build()
val cropEffect = Crop(-0.5f, 0.5f, -0.5f, 0.5f)

val effects = Effects(listOf(channelMixingProcessor), listOf(rotateEffect, cropEffect))

val editedMediaItem = EditedMediaItem.Builder(mediaItem)
    .setEffects(effects)
    .build()

ChannelMixingAudioProcessor channelMixingProcessor = new ChannelMixingAudioProcessor();
ScaleAndRotateTransformation rotateEffect = new ScaleAndRotateTransformation.Builder()
    .setRotationDegrees(60f)
    .build();
Crop cropEffect = new Crop(-0.5f, 0.5f, -0.5f, 0.5f);

Effects effects = new Effects(
    ImmutableList.of(channelMixingProcessor),
    ImmutableList.of(rotateEffect, cropEffect)
);

EditedMediaItem editedMediaItem = new EditedMediaItem.Builder(mediaItem)
    .setEffects(effects)
    .build();

إنشاء تأثيرات مخصّصة

يتيح لك توسيع التأثيرات المضمَّنة في Media3 إنشاء تأثيرات مخصّصة. الخاصة بحالات استخدامك في المثال التالي، استخدم الفئة الفرعية MatrixTransformation لتكبير الفيديو بملء الإطار فوق الأول ثانية من التشغيل:

val zoomEffect = MatrixTransformation { presentationTimeUs ->
    val transformationMatrix = Matrix()
    // Set the scaling factor based on the playback position
    val scale = min(1f, presentationTimeUs / 1_000f)
    transformationMatrix.postScale(/* x */ scale, /* y */ scale)
    transformationMatrix
}

val editedMediaItem = EditedMediaItem.Builder(inputMediaItem)
    .setEffects(Effects(listOf(), listOf(zoomEffect))
    .build()

MatrixTransformation zoomEffect = presentationTimeUs -> {
    Matrix transformationMatrix = new Matrix();
    // Set the scaling factor based on the playback position
    float scale = min(1f, presentationTimeUs / 1_000f);
    transformationMatrix.postScale(/* x */ scale, /* y */ scale);
    return transformationMatrix;
};

EditedMediaItem editedMediaItem = new EditedMediaItem.Builder(inputMediaItem)
    .setEffects(new Effects(ImmutableList.of(), ImmutableList.of(zoomEffect)))
    .build();

لتخصيص سلوك التأثير بشكل أكبر، يمكنك تنفيذ GlShaderProgram تشير رسالة الأشكال البيانية يتم استخدام أسلوب queueInputFrame() لمعالجة إطارات الإدخال. على سبيل المثال، بهدف الاستفادة من إمكانات التعلم الآلي MediaPipe، يمكنك استخدام MediaPipe FrameProcessor لإرسال كل إطار من خلال مخطط MediaPipe. الاطلاع على مثال على ذلك في تطبيق Transformer التجريبي:

معاينة التأثيرات

باستخدام ExoPlayer، يمكنك معاينة التأثيرات. تتم إضافتها إلى ملف وسائط قبل بدء عملية التصدير. استخدام نفس عنصر Effects بالنسبة إلى EditedMediaItem، يمكنك الاتصال بـ setVideoEffects() على مثيل ExoPlayer.

val player = ExoPlayer.builder(context)
    .build()
    .also { exoPlayer ->
        exoPlayer.setMediaItem(inputMediaItem)
        exoPlayer.setVideoEffects(effects)
        exoPlayer.prepare()
    }

ExoPlayer player = new ExoPlayer.builder(context).build();
player.setMediaItem(inputMediaItem);
player.setVideoEffects(effects);
exoPlayer.prepare();

ويمكنك أيضًا معاينة التأثيرات الصوتية باستخدام ExoPlayer. عند إنشاء مثيل "ExoPlayer"، يمكنك تمرير RenderersFactory مخصَّص لضبط في مشغّل الفيديو لإخراج الصوت إلى AudioSink الذي يستخدم التسلسل AudioProcessor في المثال أدناه، نفعل ذلك بتجاوز علامة طريقة buildAudioSink() من DefaultRenderersFactory.

val player = ExoPlayer.Builder(context, object : DefaultRenderersFactory(context) {
    override fun buildAudioSink(
        context: Context,
        enableFloatOutput: Boolean,
        enableAudioTrackPlaybackParams: Boolean,
        enableOffload: Boolean
    ): AudioSink? {
        return DefaultAudioSink.Builder(context)
            .setEnableFloatOutput(enableFloatOutput)
            .setEnableAudioTrackPlaybackParams(enableAudioTrackPlaybackParams)
            .setOffloadMode(if (enableOffload) {
                     DefaultAudioSink.OFFLOAD_MODE_ENABLED_GAPLESS_REQUIRED
                } else {
                    DefaultAudioSink.OFFLOAD_MODE_DISABLED
                })
            .setAudioProcessors(arrayOf(channelMixingProcessor))
            .build()
        }
    }).build()

ExoPlayer player = new ExoPlayer.Builder(context, new DefaultRenderersFactory(context) {
        @Nullable
        @Override
        protected AudioSink buildAudioSink(
            Context context,
            boolean enableFloatOutput,
            boolean enableAudioTrackPlaybackParams,
            boolean enableOffload
        ) {
            return new DefaultAudioSink.Builder(context)
                .setEnableFloatOutput(enableFloatOutput)
                .setEnableAudioTrackPlaybackParams(enableAudioTrackPlaybackParams)
                .setOffloadMode(
                    enableOffload
                        ? DefaultAudioSink.OFFLOAD_MODE_ENABLED_GAPLESS_REQUIRED
                        : DefaultAudioSink.OFFLOAD_MODE_DISABLED)
                .setAudioProcessors(new AudioProcessor[]{channelMixingProcessor})
                .build();
        }
    }).build();

بدء تحويل

أخيرًا، يجب إنشاء Transformer لتطبيق تعديلاتك وبدء تصدير ملف الوسائط الناتج.

val transformer = Transformer.Builder(context)
    .addListener(listener)
    .build()
transformer.start(editedMediaItem, outputPath)

Transformer transformer = new Transformer.Builder(context)
    .addListener(listener)
    .build();
transformer.start(editedMediaItem, outputPath);

يمكنك بالمثل إلغاء عملية التصدير إذا لزم الأمر باستخدام Transformer.cancel()

البحث عن تحديثات حول مستوى التقدّم

يعود Transformer.start على الفور ويعمل بشكل غير متزامن. للاستعلام عن التقدم الحالي لتحويل ما، طلب Transformer.getProgress() تستخدِم هذه الطريقة ProgressHolder، وإذا كانت حالة التقدّم متاحة، أي إذا أرجعت الطريقة القيمة PROGRESS_STATE_AVAILABLE، سيتم تعديل تطبيق "ProgressHolder" بالنسبة المئوية الحالية للتقدّم.

يمكنك أيضًا إرفاق المستمع إلى Transformer لتلقّي إشعارات بشأن أحداث الاكتمال أو الأخطاء.