Improve docs and split audio/video order in TransformationResult.

PiperOrigin-RevId: 500776260

library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/AndroidTestUtil.java

@@ -502,11 +502,20 @@ public final class AndroidTestUtil {
   }
 
   /**
-   * Converts an exception to a {@link JSONObject}.
+   * Creates a {@link JSONObject} from the {@link Exception}.
    *
    * <p>If the exception is a {@link TransformationException}, {@code errorCode} is included.
+   *
+   * @param exception The {@link Exception}.
+   * @return The {@link JSONObject} containing the exception details, or {@code null} if the
+   *     exception was {@code null}.
    */
-  public static JSONObject exceptionAsJsonObject(Exception exception) throws JSONException {
+  @Nullable
+  public static JSONObject exceptionAsJsonObject(@Nullable Exception exception)
+      throws JSONException {
+    if (exception == null) {
+      return null;
+    }
     JSONObject exceptionJson = new JSONObject();
     exceptionJson.put("message", exception.getMessage());
     exceptionJson.put("type", exception.getClass());

library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/TransformationTestResult.java

@@ -15,6 +15,8 @@
  */
 package com.google.android.exoplayer2.transformer;
 
+import static com.google.android.exoplayer2.transformer.AndroidTestUtil.exceptionAsJsonObject;
+
 import androidx.annotation.Nullable;
 import com.google.android.exoplayer2.C;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
@@ -29,6 +31,7 @@ public class TransformationTestResult {
   /** A builder for {@link TransformationTestResult}. */
   public static class Builder {
     private final TransformationResult transformationResult;
+
     @Nullable private String filePath;
     private long elapsedTimeMs;
     private double ssim;
@@ -142,83 +145,72 @@ public class TransformationTestResult {
     }
   }
 
+  /** The {@link TransformationResult} of the transformation. */
   public final TransformationResult transformationResult;
+  /** The path to the file created in the transformation, or {@code null} if unset. */
   @Nullable public final String filePath;
   /**
-   * The average rate (per second) at which frames are processed by the transformer, or {@link
+   * The amount of time taken to perform the transformation in milliseconds, or {@link C#TIME_UNSET}
-   * C#RATE_UNSET} if unset or unknown.
+   * if unset.
-   */
-  public final float throughputFps;
-  /**
-   * The amount of time taken to perform the transformation in milliseconds. {@link C#TIME_UNSET} if
-   * unset.
    */
   public final long elapsedTimeMs;
-  /** The SSIM score of the transformation, {@link #SSIM_UNSET} if unavailable. */
+  /**
+   * The average rate (per second) at which frames were processed by the transformer, or {@link
+   * C#RATE_UNSET} if unset.
+   */
+  public final float throughputFps;
+  /** The SSIM score of the transformation, or {@link #SSIM_UNSET} if unset. */
   public final double ssim;
   /**
    * The {@link FallbackDetails} describing the fallbacks that occurred doing transformation, or
    * {@code null} if no fallback occurred.
    */
   @Nullable public final FallbackDetails fallbackDetails;
-  /**
+  /** The {@link Exception} thrown during the test, or {@code null} if nothing was thrown. */
-   * The {@link Exception} that was thrown during the test, or {@code null} if nothing was thrown.
-   */
   @Nullable public final Exception testException;
-
   /**
-   * The {@link Exception} that was thrown during post-transformation analysis, or {@code null} if
+   * The {@link Exception} thrown during post-transformation analysis, or {@code null} if nothing
-   * nothing was thrown.
+   * was thrown.
    */
   @Nullable public final Exception analysisException;
 
   /** Returns a {@link JSONObject} representing all the values in {@code this}. */
   public JSONObject asJsonObject() throws JSONException {
-    JSONObject jsonObject = new JSONObject();
+    JSONObject jsonObject =
-    if (transformationResult.durationMs != C.LENGTH_UNSET) {
+        new JSONObject()
-      jsonObject.put("durationMs", transformationResult.durationMs);
+            .putOpt("audioDecoderName", transformationResult.audioDecoderName)
-    }
+            .putOpt("audioEncoderName", transformationResult.audioEncoderName)
-    if (transformationResult.fileSizeBytes != C.LENGTH_UNSET) {
+            .putOpt(
-      jsonObject.put("fileSizeBytes", transformationResult.fileSizeBytes);
+                "fallbackDetails", fallbackDetails != null ? fallbackDetails.asJsonObject() : null)
-    }
+            .putOpt("filePath", filePath)
+            .putOpt("videoDecoderName", transformationResult.videoDecoderName)
+            .putOpt("videoEncoderName", transformationResult.videoEncoderName)
+            .putOpt("testException", exceptionAsJsonObject(testException))
+            .putOpt("analysisException", exceptionAsJsonObject(analysisException));
+
     if (transformationResult.averageAudioBitrate != C.RATE_UNSET_INT) {
       jsonObject.put("averageAudioBitrate", transformationResult.averageAudioBitrate);
     }
     if (transformationResult.averageVideoBitrate != C.RATE_UNSET_INT) {
       jsonObject.put("averageVideoBitrate", transformationResult.averageVideoBitrate);
     }
-    if (transformationResult.videoFrameCount > 0) {
+    if (transformationResult.durationMs != C.LENGTH_UNSET) {
-      jsonObject.put("videoFrameCount", transformationResult.videoFrameCount);
+      jsonObject.put("durationMs", transformationResult.durationMs);
-    }
-    if (transformationResult.audioDecoderName != null) {
-      jsonObject.put("audioDecoderName", transformationResult.audioDecoderName);
-    }
-    if (transformationResult.videoDecoderName != null) {
-      jsonObject.put("videoDecoderName", transformationResult.videoDecoderName);
-    }
-    if (transformationResult.audioEncoderName != null) {
-      jsonObject.put("audioEncoderName", transformationResult.audioEncoderName);
-    }
-    if (transformationResult.videoEncoderName != null) {
-      jsonObject.put("videoEncoderName", transformationResult.videoEncoderName);
-    }
-    if (throughputFps != C.RATE_UNSET) {
-      jsonObject.put("throughputFps", throughputFps);
     }
     if (elapsedTimeMs != C.TIME_UNSET) {
       jsonObject.put("elapsedTimeMs", elapsedTimeMs);
     }
+    if (transformationResult.fileSizeBytes != C.LENGTH_UNSET) {
+      jsonObject.put("fileSizeBytes", transformationResult.fileSizeBytes);
+    }
     if (ssim != TransformationTestResult.SSIM_UNSET) {
       jsonObject.put("ssim", ssim);
     }
-    if (fallbackDetails != null) {
+    if (throughputFps != C.RATE_UNSET) {
-      jsonObject.put("fallbackDetails", fallbackDetails.asJsonObject());
+      jsonObject.put("throughputFps", throughputFps);
     }
-    if (testException != null) {
+    if (transformationResult.videoFrameCount > 0) {
-      jsonObject.put("testException", AndroidTestUtil.exceptionAsJsonObject(testException));
+      jsonObject.put("videoFrameCount", transformationResult.videoFrameCount);
-    }
-    if (analysisException != null) {
-      jsonObject.put("analysisException", AndroidTestUtil.exceptionAsJsonObject(analysisException));
     }
     return jsonObject;
   }

library/transformer/src/main/java/com/google/android/exoplayer2/transformer/TransformationResult.java

@@ -30,10 +30,10 @@ public final class TransformationResult {
     private long durationMs;
     private long fileSizeBytes;
     private int averageAudioBitrate;
-    private int averageVideoBitrate;
-    private int videoFrameCount;
     @Nullable private String audioDecoderName;
     @Nullable private String audioEncoderName;
+    private int averageVideoBitrate;
+    private int videoFrameCount;
     @Nullable private String videoDecoderName;
     @Nullable private String videoEncoderName;
     @Nullable private TransformationException transformationException;
@@ -46,9 +46,9 @@ public final class TransformationResult {
     }
 
     /**
-     * Sets the duration of the video in milliseconds.
+     * Sets the duration of the output in milliseconds.
      *
-     * <p>Input must be positive or {@link C#TIME_UNSET}.
+     * <p>Must be positive or {@link C#TIME_UNSET}.
      */
     @CanIgnoreReturnValue
     public Builder setDurationMs(long durationMs) {
@@ -60,7 +60,7 @@ public final class TransformationResult {
     /**
      * Sets the file size in bytes.
      *
-     * <p>Input must be positive or {@link C#LENGTH_UNSET}.
+     * <p>Must be positive or {@link C#LENGTH_UNSET}.
      */
     @CanIgnoreReturnValue
     public Builder setFileSizeBytes(long fileSizeBytes) {
@@ -72,7 +72,7 @@ public final class TransformationResult {
     /**
      * Sets the average audio bitrate.
      *
-     * <p>Input must be positive or {@link C#RATE_UNSET_INT}.
+     * <p>Must be positive or {@link C#RATE_UNSET_INT}.
      */
     @CanIgnoreReturnValue
     public Builder setAverageAudioBitrate(int averageAudioBitrate) {
@@ -81,30 +81,6 @@ public final class TransformationResult {
       return this;
     }
 
-    /**
-     * Sets the average video bitrate.
-     *
-     * <p>Input must be positive or {@link C#RATE_UNSET_INT}.
-     */
-    @CanIgnoreReturnValue
-    public Builder setAverageVideoBitrate(int averageVideoBitrate) {
-      checkArgument(averageVideoBitrate > 0 || averageVideoBitrate == C.RATE_UNSET_INT);
-      this.averageVideoBitrate = averageVideoBitrate;
-      return this;
-    }
-
-    /**
-     * Sets the number of video frames.
-     *
-     * <p>Input must be positive or {@code 0}.
-     */
-    @CanIgnoreReturnValue
-    public Builder setVideoFrameCount(int videoFrameCount) {
-      checkArgument(videoFrameCount >= 0);
-      this.videoFrameCount = videoFrameCount;
-      return this;
-    }
-
     /** Sets the name of the audio decoder used. */
     @CanIgnoreReturnValue
     public Builder setAudioDecoderName(@Nullable String audioDecoderName) {
@@ -119,6 +95,30 @@ public final class TransformationResult {
       return this;
     }
 
+    /**
+     * Sets the average video bitrate.
+     *
+     * <p>Must be positive or {@link C#RATE_UNSET_INT}.
+     */
+    @CanIgnoreReturnValue
+    public Builder setAverageVideoBitrate(int averageVideoBitrate) {
+      checkArgument(averageVideoBitrate > 0 || averageVideoBitrate == C.RATE_UNSET_INT);
+      this.averageVideoBitrate = averageVideoBitrate;
+      return this;
+    }
+
+    /**
+     * Sets the number of video frames.
+     *
+     * <p>Must be positive or {@code 0}.
+     */
+    @CanIgnoreReturnValue
+    public Builder setVideoFrameCount(int videoFrameCount) {
+      checkArgument(videoFrameCount >= 0);
+      this.videoFrameCount = videoFrameCount;
+      return this;
+    }
+
     /** Sets the name of the video decoder used. */
     @CanIgnoreReturnValue
     public Builder setVideoDecoderName(@Nullable String videoDecoderName) {
@@ -146,10 +146,10 @@ public final class TransformationResult {
           durationMs,
           fileSizeBytes,
           averageAudioBitrate,
-          averageVideoBitrate,
-          videoFrameCount,
           audioDecoderName,
           audioEncoderName,
+          averageVideoBitrate,
+          videoFrameCount,
           videoDecoderName,
           videoEncoderName,
           transformationException);
@@ -160,24 +160,27 @@ public final class TransformationResult {
   public final long durationMs;
   /** The size of the file in bytes, or {@link C#LENGTH_UNSET} if unset or unknown. */
   public final long fileSizeBytes;
+
   /**
    * The average bitrate of the audio track data, or {@link C#RATE_UNSET_INT} if unset or unknown.
    */
   public final int averageAudioBitrate;
+  /** The name of the audio decoder used, or {@code null} if none were used. */
+  @Nullable public final String audioDecoderName;
+  /** The name of the audio encoder used, or {@code null} if none were used. */
+  @Nullable public final String audioEncoderName;
+
   /**
    * The average bitrate of the video track data, or {@link C#RATE_UNSET_INT} if unset or unknown.
    */
   public final int averageVideoBitrate;
   /** The number of video frames. */
   public final int videoFrameCount;
-  /** The name of the audio decoder used, or {@code null} if none were used. */
-  @Nullable public final String audioDecoderName;
-  /** The name of the audio encoder used, or {@code null} if none were used. */
-  @Nullable public final String audioEncoderName;
   /** The name of the video decoder used, or {@code null} if none were used. */
   @Nullable public final String videoDecoderName;
   /** The name of the video encoder used, or {@code null} if none were used. */
   @Nullable public final String videoEncoderName;
+
   /**
    * The {@link TransformationException} that caused the transformation to fail, or {@code null} if
    * the transformation was a success.
@@ -188,20 +191,20 @@ public final class TransformationResult {
       long durationMs,
       long fileSizeBytes,
       int averageAudioBitrate,
-      int averageVideoBitrate,
-      int videoFrameCount,
       @Nullable String audioDecoderName,
       @Nullable String audioEncoderName,
+      int averageVideoBitrate,
+      int videoFrameCount,
       @Nullable String videoDecoderName,
       @Nullable String videoEncoderName,
       @Nullable TransformationException transformationException) {
     this.durationMs = durationMs;
     this.fileSizeBytes = fileSizeBytes;
     this.averageAudioBitrate = averageAudioBitrate;
-    this.averageVideoBitrate = averageVideoBitrate;
-    this.videoFrameCount = videoFrameCount;
     this.audioDecoderName = audioDecoderName;
     this.audioEncoderName = audioEncoderName;
+    this.averageVideoBitrate = averageVideoBitrate;
+    this.videoFrameCount = videoFrameCount;
     this.videoDecoderName = videoDecoderName;
     this.videoEncoderName = videoEncoderName;
     this.transformationException = transformationException;
@@ -212,10 +215,10 @@ public final class TransformationResult {
         .setDurationMs(durationMs)
         .setFileSizeBytes(fileSizeBytes)
         .setAverageAudioBitrate(averageAudioBitrate)
-        .setAverageVideoBitrate(averageVideoBitrate)
-        .setVideoFrameCount(videoFrameCount)
         .setAudioDecoderName(audioDecoderName)
         .setAudioEncoderName(audioEncoderName)
+        .setAverageVideoBitrate(averageVideoBitrate)
+        .setVideoFrameCount(videoFrameCount)
         .setVideoDecoderName(videoDecoderName)
         .setVideoEncoderName(videoEncoderName)
         .setTransformationException(transformationException);
@@ -233,10 +236,10 @@ public final class TransformationResult {
     return durationMs == result.durationMs
         && fileSizeBytes == result.fileSizeBytes
         && averageAudioBitrate == result.averageAudioBitrate
-        && averageVideoBitrate == result.averageVideoBitrate
-        && videoFrameCount == result.videoFrameCount
         && Objects.equals(audioDecoderName, result.audioDecoderName)
         && Objects.equals(audioEncoderName, result.audioEncoderName)
+        && averageVideoBitrate == result.averageVideoBitrate
+        && videoFrameCount == result.videoFrameCount
         && Objects.equals(videoDecoderName, result.videoDecoderName)
         && Objects.equals(videoEncoderName, result.videoEncoderName)
         && Objects.equals(transformationException, result.transformationException);
@@ -247,10 +250,10 @@ public final class TransformationResult {
     int result = (int) durationMs;
     result = 31 * result + (int) fileSizeBytes;
     result = 31 * result + averageAudioBitrate;
-    result = 31 * result + averageVideoBitrate;
-    result = 31 * result + videoFrameCount;
     result = 31 * result + Objects.hashCode(audioDecoderName);
     result = 31 * result + Objects.hashCode(audioEncoderName);
+    result = 31 * result + averageVideoBitrate;
+    result = 31 * result + videoFrameCount;
     result = 31 * result + Objects.hashCode(videoDecoderName);
     result = 31 * result + Objects.hashCode(videoEncoderName);
     result = 31 * result + Objects.hashCode(transformationException);