feat: Add Archive.quantizationParameter (#577)

Author: SMadani

CHANGELOG.md

@@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 # [8.20.0] - 2025-03-19
+- Added `quantizationParameter` to Video Archive
 - Fixed custom event type parsing and creation in Conversation API
 - Added support for the following event types in Conversation API:
   - `member:invited`

src/main/java/com/vonage/client/video/Archive.java

@@ -31,6 +31,7 @@ public class Archive extends StreamComposition {
     private URI url;
     private ArchiveStatus status;
     private OutputMode outputMode;
+    private Integer quantizationParameter;
 
     protected Archive() {
     }
@@ -52,6 +53,14 @@ protected Archive(Builder builder) {
         if ((maxBitrate = builder.maxBitrate) != null && (maxBitrate < 100000 || maxBitrate > 6000000)) {
             throw new IllegalArgumentException("Maximum bitrate must be between 100000 and 6000000.");
         }
+        if ((quantizationParameter = builder.quantizationParameter) != null) {
+            if (maxBitrate != null) {
+                throw new IllegalStateException("Quantization parameter is mutually exclusive with maxBitrate.");
+            }
+            if (quantizationParameter < 15 || quantizationParameter > 40) {
+                throw new IllegalArgumentException("Quantization parameter must be between 15 and 40.");
+            }
+        }
     }
 
     /**
@@ -149,6 +158,17 @@ public String getMultiArchiveTag() {
         return multiArchiveTag;
     }
 
+    /**
+     * Returns the quantization parameter if set for the Archive.
+     *
+     * @return The quantization parameter, or {@code null} if not applicable.
+     * @since 8.20.0
+     */
+    @JsonProperty("quantizationParameter")
+    public Integer getQuantizationParameter() {
+        return quantizationParameter;
+    }
+
     /**
      * Creates an instance of this class from a JSON payload.
      *
@@ -179,6 +199,7 @@ public static Builder builder(String sessionId) {
     public static class Builder extends StreamComposition.Builder {
         private String name, multiArchiveTag;
         private OutputMode outputMode;
+        private Integer quantizationParameter;
 
         Builder(String sessionId) {
             this.sessionId = sessionId;
@@ -317,6 +338,21 @@ public Builder maxBitrate(int maxBitrate) {
             return this;
         }
 
+        /**
+         * (OPTIONAL) Quantization Parameter (QP) is an optional video encoding value allowed for composed archiving,
+         * smaller values generate higher quality and larger archives, larger values generate lower quality and smaller
+         * archives, QP uses variable bitrate (VBR). This must be between 15 and 40.
+         *
+         * @param quantizationParameter The quantization parameter as an integer (minimum 15, maximum 40).
+         *
+         * @return This builder.
+         * @since 8.20.0
+         */
+        public Builder quantizationParameter(int quantizationParameter) {
+            this.quantizationParameter = quantizationParameter;
+            return this;
+        }
+
         /**
          * Builds the {@linkplain Archive} object with this builder's settings.
          *

src/test/java/com/vonage/client/video/ArchiveTest.java

@@ -15,7 +15,7 @@
  */
 package com.vonage.client.video;
 
-import com.vonage.client.TestUtils;
+import static com.vonage.client.TestUtils.testJsonableBaseObject;
 import com.vonage.client.VonageResponseParseException;
 import static org.junit.jupiter.api.Assertions.*;
 import org.junit.jupiter.api.*;
@@ -38,7 +38,7 @@ public void testSerializeAllParams() {
 				.streamMode(StreamMode.AUTO).layout(layout)
 				.multiArchiveTag(multiArchiveTag).build();
 
-		TestUtils.testJsonableBaseObject(request);
+		testJsonableBaseObject(request);
 		String json = request.toJson();
 		assertTrue(json.contains("\"name\":\""+name+"\""));
 		assertTrue(json.contains("\"multiArchiveTag\":\""+multiArchiveTag+"\""));
@@ -52,6 +52,30 @@ public void testSerializeAllParams() {
 		assertTrue(json.contains("\"maxBitrate\":"+maxBitrate));
 	}
 
+	@Test
+	public void testQuantizationParameter() {
+		String sessionId = "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN";
+		int qp = 19;
+		Archive request = Archive.builder(sessionId).quantizationParameter(qp).build();
+		testJsonableBaseObject(request);
+		String json = request.toJson();
+		assertTrue(json.contains("\"sessionId\":\""+sessionId+"\""));
+		assertTrue(json.contains("\"quantizationParameter\":"+qp));
+		assertThrows(IllegalStateException.class, () ->
+				Archive.builder(sessionId).quantizationParameter(qp).maxBitrate(213450).build()
+		);
+	}
+
+	@Test
+	public void testQuantizationParameterBounds() {
+		var builder = Archive.builder("SESSION_ID");
+		int min = 15, max = 40;
+		assertThrows(IllegalArgumentException.class, () -> builder.quantizationParameter(min-1).build());
+		assertEquals(min, builder.quantizationParameter(min).build().getQuantizationParameter());
+		assertThrows(IllegalArgumentException.class, () -> builder.quantizationParameter(max+1).build());
+		assertEquals(max, builder.quantizationParameter(max).build().getQuantizationParameter());
+	}
+
 	@Test
 	public void testSerializeCustomLayout() {
 		String style = "stream.instructor {position: absolute; width: 100%;  height:50%;}";
@@ -62,7 +86,7 @@ public void testSerializeCustomLayout() {
 				.streamMode(StreamMode.MANUAL).layout(layout)
 				.outputMode(OutputMode.COMPOSED).build();
 
-		TestUtils.testJsonableBaseObject(request);
+		testJsonableBaseObject(request);
 		String json = request.toJson();
 		assertTrue(json.contains("\"outputMode\":\"composed\""));
 		assertTrue(json.contains("\"streamMode\":\"manual\""));
@@ -130,5 +154,6 @@ public void testFromJsonEmpty() {
 		assertNull(archive.getDurationSeconds());
 		assertNull(archive.getCreatedAt());
 		assertNull(archive.getCreatedAtMillis());
+		assertNull(archive.getQuantizationParameter());
 	}
 }