ליצור אפליקציה בסיסית לעריכת סרטונים באמצעות Media3 Transformer

ממשקי ה-API של Transformer ב-Jetpack Media3 נועדו לשפר את הביצועים והאמינות של עריכת המדיה. Transformer תומך במספר פעולות, כולל:

• שינוי סרטון באמצעות חיתוך, שינוי קנה מידה וסיבוב
• הוספת אפקטים כמו שכבות-על ופילטרים
• עיבוד פורמטים מיוחדים כמו HDR וסרטונים בהילוך איטי
• ייצוא פריט מדיה אחרי החלת העריכות

בדף הזה נסביר על כמה מהתרחישים העיקריים לדוגמה שבהם Transformer יכול לעזור. לפרטים נוספים, אפשר לעיין במדריכים המלאים שלנו בנושא Media3 Transformer.

שנתחיל?

כדי להתחיל, מוסיפים יחסי תלות למודולים Transformer,‏ Effect ו-Common של Jetpack Media3:

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

חשוב להחליף את 1.5.0 בגרסה המועדפת של הספרייה. אפשר לעיין בנתוני הגרסה כדי לראות מהי הגרסה האחרונה.

כיתות חשובות

הגדרת הפלט

בעזרת 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();

אם פורמט המדיה של הקלט כבר תואם לבקשת הטרנספורמציה של האודיו או הסרטון, Transformer עובר באופן אוטומטי להמרת קודק, כלומר העתקת הדגימות הדחוסות ממאגר הקלט למאגר הפלט ללא שינוי. כך אפשר להימנע מהעלות החישובית ומאובדן האיכות הפוטנציאלי של פעולות הפענוח והקידוד מחדש באותו פורמט.

הגדרת מצב HDR

אם קובץ המדיה בקלט הוא בפורמט HDR, אפשר לבחור בין כמה מצבים שונים של עיבוד המידע ב-HDR על ידי Transformer. מומלץ להשתמש ב-HDR_MODE_KEEP_HDR או ב-HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL.

במכשירים שתומכים ביכולות הקידוד הנדרשות ומריצים את Android 13 (רמת API 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 מותאם אישית שמגדיר את ה-audio renderers של הנגן להפיק אודיו ל-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 כדי לקבל התראות על אירועי השלמה או שגיאה.