Improve docs and split audio/video order in TransformationResult.

PiperOrigin-RevId: 500776260

Improve docs and split audio/video order in TransformationResult.
PiperOrigin-RevId: 500776260
b3831778 · samrobinson · christosts · 886063d6 · b3831778 · b3831778
Commit b3831778 authored Jan 09, 2023 by samrobinson Committed by christosts Jan 10, 2023
Showing with 88 additions and 84 deletions
library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/AndroidTestUtil.java
library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/TransformationTestResult.java
library/transformer/src/main/java/com/google/android/exoplayer2/transformer/TransformationResult.java
--- a/library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/AndroidTestUtil.java
+++ b/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());

--- a/library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/TransformationTestResult.java
+++ b/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;
+  public final long elapsedTimeMs;
  /**
-   * The amount of time taken to perform the transformation in milliseconds. {@link C#TIME_UNSET} if
+   * The average rate (per second) at which frames were processed by the transformer, or {@link
-   * unset.
+   * C#RATE_UNSET} if unset.
   */
-  public final long elapsedTimeMs;
+  public final float throughputFps;
-  /** The SSIM score of the transformation, {@link #SSIM_UNSET} if unavailable. */
+  /** 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) {
-      jsonObject.put("testException", AndroidTestUtil.exceptionAsJsonObject(testException));
    }
-    if (analysisException != null) {
+    if (transformationResult.videoFrameCount > 0) {
-      jsonObject.put("analysisException", AndroidTestUtil.exceptionAsJsonObject(analysisException));
+      jsonObject.put("videoFrameCount", transformationResult.videoFrameCount);
    }
    return jsonObject;
  }

--- a/library/transformer/src/main/java/com/google/android/exoplayer2/transformer/TransformationResult.java
+++ b/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,10 +81,24 @@ public final class TransformationResult {
      return this;
    }
+    /** Sets the name of the audio decoder used. */
+    @CanIgnoreReturnValue
+    public Builder setAudioDecoderName(@Nullable String audioDecoderName) {
+      this.audioDecoderName = audioDecoderName;
+      return this;
+    }
+    /** Sets the name of the audio encoder used. */
+    @CanIgnoreReturnValue
+    public Builder setAudioEncoderName(@Nullable String audioEncoderName) {
+      this.audioEncoderName = audioEncoderName;
+      return this;
+    }
    /**
     * Sets the average video 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 setAverageVideoBitrate(int averageVideoBitrate) {
@@ -96,7 +110,7 @@ public final class TransformationResult {
    /**
     * Sets the number of video frames.
     *
-     * <p>Input must be positive or {@code 0}.
+     * <p>Must be positive or {@code 0}.
     */
    @CanIgnoreReturnValue
    public Builder setVideoFrameCount(int videoFrameCount) {
@@ -105,20 +119,6 @@ public final class TransformationResult {
      return this;
    }
-    /** Sets the name of the audio decoder used. */
-    @CanIgnoreReturnValue
-    public Builder setAudioDecoderName(@Nullable String audioDecoderName) {
-      this.audioDecoderName = audioDecoderName;
-      return this;
-    }
-    /** Sets the name of the audio encoder used. */
-    @CanIgnoreReturnValue
-    public Builder setAudioEncoderName(@Nullable String audioEncoderName) {
-      this.audioEncoderName = audioEncoderName;
-      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);