Skip to content

Commit 9860b85

Browse files
seymourtangseymourtang
committed
Enhance cloud recording API documentation and update method references
- Added detailed documentation for `LayoutConfig` and `BackgroundConfig` classes in `UpdateLayoutResourceReq`. - Updated method references in various classes to use lowercase for API names (e.g., `start`, `stop`, `update`). - Improved clarity of comments in `IndividualScenario`, `MixScenario`, and `WebScenario` classes regarding request and response handling. - Ensured consistency in API documentation across multiple response classes related to cloud recording.
1 parent 6183482 commit 9860b85

16 files changed

+283
-161
lines changed

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/req/UpdateLayoutResourceReq.java‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,26 +246,102 @@ public String toString() {
246246
}
247247
}
248248

249+
/**
250+
* @brief Configurations of user's video window to be updated.
251+
* @since v0.4.0
252+
*/
249253
public static class LayoutConfig {
250254

255+
/**
256+
* The content of the string is the UID of the user to be displayed in the area,
257+
* 32-bit unsigned integer.
258+
*/
251259
@JsonProperty("uid")
252260
private String uid;
253261

262+
/**
263+
* The relative value of the horizontal coordinate of the upper-left corner of
264+
* the screen, accurate to six decimal places.
265+
* <p>
266+
* Layout from left to right, with 0.0 at the far left and 1.0 at the far right.
267+
* <p>
268+
* This field can also be set to the integer 0 or 1.
269+
* <p>
270+
* The value range is [0,1].
271+
*/
254272
@JsonProperty("x_axis")
255273
private Float xAxis;
256274

275+
/**
276+
* The relative value of the vertical coordinate of the upper-left corner of
277+
* this screen in the screen, accurate to six decimal places.
278+
* <p>
279+
* Layout from top to bottom, with 0.0 at the top and 1.0 at the bottom.
280+
* <p>
281+
* This field can also be set to the integer 0 or 1.
282+
* <p>
283+
* The value range is [0,1].
284+
*/
257285
@JsonProperty("y_axis")
258286
private Float yAxis;
259287

288+
/**
289+
* The relative value of the width of this screen, accurate to six decimal
290+
* places.
291+
* <p>
292+
* This field can also be set to the integer 0 or 1.
293+
* <p>
294+
* The value range is [0,1].
295+
*/
260296
@JsonProperty("width")
261297
private Float width;
262298

299+
/**
300+
* The relative value of the height of this screen, accurate to six decimal
301+
* places.
302+
* <p>
303+
* This field can also be set to the integer 0 or 1.
304+
* <p>
305+
* The value range is [0,1].
306+
*/
263307
@JsonProperty("height")
264308
private Float height;
265309

310+
/**
311+
* The transparency of the user's video window. Accurate to six decimal places.
312+
* <p>
313+
* 0.0 means the user's video window is transparent, and 1.0 indicates that it
314+
* is completely opaque.
315+
* <p>
316+
* The value range is [0,1].
317+
* <p>
318+
* The default value is 1.
319+
*/
266320
@JsonProperty("alpha")
267321
private Float alpha;
268322

323+
/**
324+
* The display mode of users' video windows.
325+
* <p>
326+
* The rendering mode can be set to:
327+
* <p>
328+
* - 0: Cropped mode.(Default)
329+
* Prioritize to ensure the screen is filled.
330+
* The video window size is proportionally scaled until it fills the screen.
331+
* If the video's length and width differ from the video window,
332+
* the video stream will be cropped from its edges to fit the window,
333+
* under the aspect ratio set for the video window.
334+
* <p>
335+
* - 1: Fit mode.
336+
* Prioritize to ensure that all video content is displayed.
337+
* The video size is scaled proportionally until one side of the video window is
338+
* aligned with the screen border.
339+
* If the video scale does not comply with the window size,
340+
* the video will be scaled to fill the screen while maintaining its aspect
341+
* ratio.
342+
* <p>
343+
* This scaling may result in a black border around the edges of the video.
344+
*/
269345
@JsonProperty("render_mode")
270346
private Integer renderMode;
271347

@@ -412,14 +488,56 @@ public String toString() {
412488
}
413489
}
414490

491+
/**
492+
* @brief Configurations of user's background image to be updated.
493+
* @since v0.4.0
494+
*/
415495
public static class BackgroundConfig {
416496

497+
/**
498+
* The string content is the UID.(Required)
499+
*/
417500
@JsonProperty("uid")
418501
private String uid;
419502

503+
/**
504+
* The URL of the user's background image.(Required)
505+
* <p>
506+
* After setting the background image, if the user stops sending the video
507+
* stream for more than 3.5 seconds,
508+
* the screen will switch to the background image.
509+
* <p>
510+
* URL supports the HTTP and HTTPS protocols, and the image formats supported
511+
* are JPG and BMP.
512+
* <p>
513+
* The image size must not exceed 6 MB.
514+
* <p>
515+
* The settings will only take effect after the recording service successfully
516+
* downloads the image;
517+
* if the download fails, the settings will not take effect.
518+
* <p>
519+
* Different field settings may overlap each other.
520+
*/
420521
@JsonProperty("image_url")
421522
private String imageURL;
422523

524+
/**
525+
* The display mode of users' video windows.(Optional)
526+
* <p>
527+
* The value can be set to:
528+
* <p>
529+
* - 0: cropped mode.(Default)
530+
* Prioritize to ensure the screen is filled.
531+
* The video window size is proportionally scaled until it fills the screen.
532+
* If the video's length and width differ from the video window,
533+
* the video stream will be cropped from its edges to fit the window, under the
534+
* aspect ratio set for the video window.
535+
* <p>
536+
* - 1: Fit mode.
537+
* Prioritize to ensure that all video content is displayed.
538+
* The video size is scaled proportionally until one side of the video window is
539+
* aligned with the screen border.
540+
*/
423541
@JsonProperty("render_mode")
424542
private Integer renderMode;
425543

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/res/AcquireResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44

55
/**
6-
* @brief Returned by the various of cloud recording scenarios Acquire API.
6+
* @brief Returned by the various of cloud recording scenarios acquire API.
77
* @since v0.4.0
88
*/
99
public class AcquireResourceRes {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/res/QueryResourceRes.java‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,7 @@ public enum ServerResponseType {
254254
}
255255

256256
/**
257-
* @brief Server response returned by the individual recording Query API.
257+
* @brief Server response returned by the individual recording query API.
258258
* @since v0.4.0
259259
*/
260260
public static class QueryIndividualRecordingServerResponse {
@@ -467,7 +467,7 @@ public String toString() {
467467

468468
/**
469469
* @brief Server response returned by the individual recording
470-
* QueryVideoScreenshot API.
470+
* queryVideoScreenshot API.
471471
* @since v0.4.0
472472
*/
473473
public static class QueryIndividualVideoScreenshotServerResponse {
@@ -529,7 +529,7 @@ public String toString() {
529529
}
530530

531531
/**
532-
* @brief Server response returned by the mix recording QueryHLS API.
532+
* @brief Server response returned by the mix recording queryHLS API.
533533
* @since v0.4.0
534534
*/
535535
public static class MixRecordingHLSServerResponse {
@@ -627,7 +627,7 @@ public String toString() {
627627
}
628628

629629
/**
630-
* @brief Server response returned by the mix recording QueryHLSAndMP4 API.
630+
* @brief Server response returned by the mix recording queryHLSAndMP4 API.
631631
* @since v0.4.0
632632
*/
633633
public static class MixRecordingHLSAndMP4ServerResponse {
@@ -802,7 +802,7 @@ public String toString() {
802802
}
803803

804804
/**
805-
* @brief Server response returned by the web recording Query API.
805+
* @brief Server response returned by the web recording query API.
806806
* @since v0.4.0
807807
*/
808808
public static class WebRecordingServerResponse {
@@ -1002,7 +1002,7 @@ public String toString() {
10021002
}
10031003

10041004
/**
1005-
* @brief Server response returned by the web recording Query API.
1005+
* @brief Server response returned by the web recording query API.
10061006
* @since v0.4.0
10071007
*/
10081008
public static class WebRecordingRtmpPublishServerResponse {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/res/StartResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44

55
/**
6-
* @brief Returned by the various of cloud recording scenarios Start API.
6+
* @brief Returned by the various of cloud recording scenarios start API.
77
* @since v0.4.0
88
*/
99
public class StartResourceRes {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/res/StopResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44

55
/**
6-
* @brief Returned by the various of cloud recording scenarios Stop API.
6+
* @brief Returned by the various of cloud recording scenarios stop API.
77
* @since v0.4.0
88
*/
99
public class StopResourceRes {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/res/UpdateLayoutResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44

55
/**
6-
* @brief Returned by the mix recording UpdateLayout API.
6+
* @brief Returned by the mix recording updateLayout API.
77
* @since v0.4.0
88
*/
99
public class UpdateLayoutResourceRes {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/api/res/UpdateResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44

55
/**
6-
* @brief Returned by the various of cloud recording scenarios Update API.
6+
* @brief Returned by the various of cloud recording scenarios update API.
77
* @since v0.4.0
88
*/
99
public class UpdateResourceRes {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/scenario/individual/IndividualScenario.java‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ public abstract class IndividualScenario {
1616
/**
1717
* @brief Get a resource ID for individual cloud recording.
1818
* @since v0.4.0
19-
* @post After receiving the resource ID, call the Start API to start cloud
19+
* @post After receiving the resource ID, call the start API to start cloud
2020
* recording.
2121
* @param cname The name of the channel to be recorded.
2222
* @param uid The user ID used by the cloud recording service in the
@@ -26,9 +26,10 @@ public abstract class IndividualScenario {
2626
* - true: Postpone the recording.
2727
* - false: Start the recording immediately.
2828
* @param clientRequest The request body. See
29-
* AcquireIndividualResourceClientReq for details.
30-
* @return Returns the response AcquireResourceRes. See AcquireResourceRes for
31-
* details.
29+
* {@link AcquireIndividualResourceClientReq} for
30+
* details.
31+
* @return Returns the acquire resource result. See
32+
* {@link AcquireResourceRes} for details.
3233
*/
3334
public abstract Mono<AcquireResourceRes> acquire(String cname, String uid, boolean enablePostpone,
3435
AcquireIndividualResourceClientReq clientRequest);
@@ -39,10 +40,11 @@ public abstract Mono<AcquireResourceRes> acquire(String cname, String uid, boole
3940
* @param cname Channel name.
4041
* @param uid User ID.
4142
* @param resourceId The resource ID.
42-
* @param clientRequest The request body. See StartIndividualRecordingClientReq
43-
* for details.
44-
* @return Returns the response StartResourceRes. See StartResourceRes for
45-
* details.
43+
* @param clientRequest The request body. See
44+
* {@link StartIndividualRecordingClientReq} for
45+
* details.
46+
* @return Returns the start resource result. See
47+
* {@link StartResourceRes} for details.
4648
*/
4749
public abstract Mono<StartResourceRes> start(String cname, String uid, String resourceId,
4850
StartIndividualRecordingClientReq clientRequest);
@@ -53,8 +55,8 @@ public abstract Mono<StartResourceRes> start(String cname, String uid, String re
5355
* @since v0.4.0
5456
* @param resourceId The resource ID.
5557
* @param sid The recording ID, identifying a recording cycle.
56-
* @return Returns the response QueryIndividualRecordingResourceRes. See
57-
* QueryIndividualRecordingResourceRes for details.
58+
* @return Returns the query recording resource result. See
59+
* {@link QueryIndividualRecordingResourceRes} for details.
5860
*/
5961
public abstract Mono<QueryIndividualRecordingResourceRes> query(String resourceId, String sid);
6062

@@ -64,9 +66,10 @@ public abstract Mono<StartResourceRes> start(String cname, String uid, String re
6466
* @since v0.4.0
6567
* @param resourceId The resource ID.
6668
* @param sid The recording ID, identifying a recording cycle.
67-
* @return Returns the response
68-
* QueryIndividualRecordingVideoScreenshotResourceRes. See
69-
* QueryIndividualRecordingVideoScreenshotResourceRes for details.
69+
* @return Returns the query recording resource result when video screenshot
70+
* capture is turned on. See
71+
* {@link QueryIndividualRecordingVideoScreenshotResourceRes} for
72+
* details.
7073
*/
7174
public abstract Mono<QueryIndividualRecordingVideoScreenshotResourceRes> queryVideoScreenshot(String resourceId,
7275
String sid);
@@ -81,9 +84,10 @@ public abstract Mono<QueryIndividualRecordingVideoScreenshotResourceRes> queryVi
8184
* @param resourceId The resource ID.
8285
* @param sid The recording ID, identifying a recording cycle.
8386
* @param clientRequest The request body. See
84-
* UpdateIndividualRecordingResourceClientReq for details.
85-
* @return Returns the response UpdateResourceRes. See UpdateResourceRes for
86-
* details.
87+
* {@link UpdateIndividualRecordingResourceClientReq} for
88+
* details.
89+
* @return Returns the update resource result. See
90+
* {@link UpdateResourceRes} for details.
8791
*/
8892
public abstract Mono<UpdateResourceRes> update(String cname, String uid, String resourceId, String sid,
8993
UpdateIndividualRecordingResourceClientReq clientRequest);
@@ -101,7 +105,7 @@ public abstract Mono<UpdateResourceRes> update(String cname, String uid, String
101105
* - true: Stop the recording asynchronously.
102106
* <p>
103107
* - false: Stop the recording synchronously.
104-
* @return Returns the response StopResourceRes. See StopResourceRes for
108+
* @return Returns the stop resource result. See {@link StopResourceRes} for
105109
* details.
106110
*/
107111
public abstract Mono<StopResourceRes> stop(String cname, String uid, String resourceId, String sid,

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/scenario/individual/res/QueryIndividualRecordingResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import io.agora.rest.services.cloudrecording.api.res.QueryResourceRes;
44

55
/**
6-
* @brief Response returned by the individual recording Query API.
6+
* @brief Response returned by the individual recording query API.
77
* @since v0.4.0
88
*/
99
public class QueryIndividualRecordingResourceRes {

‎agora-rest-client-core/src/main/java/io/agora/rest/services/cloudrecording/scenario/individual/res/QueryIndividualRecordingVideoScreenshotResourceRes.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import io.agora.rest.services.cloudrecording.api.res.QueryResourceRes;
44

55
/**
6-
* @brief Response returned by the individual recording QueryVideoScreenshot
6+
* @brief Response returned by the individual recording queryVideoScreenshot
77
* API.
88
* @since v0.4.0
99
*/

0 commit comments

Comments
 (0)