All Products
Search

This Product

    ApsaraVideo Live:Developer guide

    Document Center

    ApsaraVideo Live:Developer guide

    Last Updated:Aug 09, 2023

    This topic describes how to use the API operations that are related to the production studio feature.

    Notes

    • This topic discusses the production studio feature based on only API operations, which is different from actual production studios. To use the production studio feature based on API operations, you must develop a frontend web page that allows interaction.

    • The ApsaraVideo Live console provides production studios and a frontend web page for you to orchestrate videos. If you use production studios in the console, you can skip this topic. For more information, see Get started with a production studio.

    Intended readers

    • Java or PHP developers. For more information, see Use the server SDK for Java.

    • Developers who understand the basic capabilities of the production studio feature.

    • Developers who understand the basic features of ApsaraVideo Live.

    Prerequisites

    Procedure

    1. Configure a production studio.

      Description

      After you create a production studio, you can configure the settings of the production studio based on your business requirements, such as the production studio name, domain name, transcoding, recording, stream delay, and standby resource.

      API operations

      Item

      Description

      SetCasterConfig

      Configures a production studio.

      domainName

      Binds a custom domain name to the production studio.

      casterTemplate

      Sets the resolution of videos that are generated by the production studio.

      liveTemplate

      Sets the parameters that are related to live stream transcoding for the production studio.

      recordConfig

      Sets the parameters that are related to live stream recording for the production studio.

      Sample code

      AddCasterVideoResourceRequest addCasterVideoResourceRequest = new AddCasterVideoResourceRequest();
addCasterVideoResourceRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterVideoResourceRequest.setResourceName("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterVideoResourceRequest.setLocationId("RV01" ); // The values that range from RV01 to RV06 indicate the IDs of the locations in the PVW window. The specified ID must be unique. A layout references a video based on its location ID.
addCasterVideoResourceRequest.setLiveStreamUrl( null); // This parameter can be left empty if the video source is an on-demand video.
addCasterVideoResourceRequest.setMaterialId("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterVideoResourceRequest.setRepeatNum(-1); // The video is played in loop mode.
AddCasterVideoResourceResponse response = client.getAcsResponse(addCasterVideoResourceRequest);

// ModifyCasterVideoResource: Modifies a video source.
ModifyCasterVideoResourceRequest modifyCasterVideoResourceRequest = new ModifyCasterVideoResourceRequest();
modifyCasterVideoResourceRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterVideoResourceRequest.setResourceId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterVideoResourceRequest.setLiveStreamUrl("rtmp://192.168.1.1");
modifyCasterVideoResourceRequest.setResourceName("LIVEPRODUCER_POST-cn-0pp123h****");
ModifyCasterVideoResourceResponse response = client.getAcsResponse(modifyCasterVideoResourceRequest);

// DescribeCasterVideoResources: Queries video sources.
DescribeCasterVideoResourcesRequest describeCasterVideoResourcesRequest = new DescribeCasterVideoResourcesRequest();
describeCasterVideoResourcesRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
DescribeCasterVideoResourcesResponse response = client.getAcsResponse(describeCasterVideoResourcesRequest);

// DeleteCasterVideoResource: Deletes a video source.
DeleteCasterVideoResourceRequest deleteCasterVideoResourceRequest = new DeleteCasterVideoResourceRequest();
deleteCasterVideoResourceRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
deleteCasterVideoResourceRequest.setResourceId("LIVEPRODUCER_POST-cn-0pp123h****");
DeleteCasterVideoResourceResponse response = client.getAcsResponse(deleteCasterVideoResourceRequest);

    2. Edit video sources.

      Description

      Configure video sources that are used to produce the output content. You can use live streams and on-demand videos as video sources.

      API operations

      Item

      Description

      AddCasterVideoResource

      Adds a video source.

      ModifyCasterVideoResource

      Modifies a video source.

      DescribeCasterVideoResources

      Queries video sources.

      DeleteCasterVideoResource

      Deletes a video source.

      liveStreamUrl

      Specifies the streaming URL that is required if the video source is a live stream.

      materialId

      Specifies the video ID that is required if the video source is an on-demand video. In addition, you can use the repeatNum parameter to specify the number of playback times in loop mode.

      locationId

      Specifies the name and location ID of the video source. The location ID can be referenced by a layout.

      Sample code

      // AddCasterVideoResource: Adds a video source.
AddCasterVideoResourceRequest addCasterVideoResourceRequest = new AddCasterVideoResourceRequest();
addCasterVideoResourceRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterVideoResourceRequest.setResourceName("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterVideoResourceRequest.setLocationId("RV01" ); // The values that range from RV01 to RV06 indicate the IDs of the locations in the PVW window. The specified ID must be unique. A layout references a video based on its location ID.
addCasterVideoResourceRequest.setLiveStreamUrl( null); // This parameter can be left empty if the video source is an on-demand video.
addCasterVideoResourceRequest.setMaterialId("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterVideoResourceRequest.setRepeatNum(-1); // The video is played in loop mode.
AddCasterVideoResourceResponse response = client.getAcsResponse(addCasterVideoResourceRequest);

// ModifyCasterVideoResource: Modifies a video source.
ModifyCasterVideoResourceRequest modifyCasterVideoResourceRequest = new ModifyCasterVideoResourceRequest();
modifyCasterVideoResourceRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterVideoResourceRequest.setResourceId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterVideoResourceRequest.setLiveStreamUrl("rtmp://192.168.1.1");
modifyCasterVideoResourceRequest.setResourceName("LIVEPRODUCER_POST-cn-0pp123h****");
ModifyCasterVideoResourceResponse response = client.getAcsResponse(modifyCasterVideoResourceRequest);

// DescribeCasterVideoResources: Queries video sources.
DescribeCasterVideoResourcesRequest describeCasterVideoResourcesRequest = new DescribeCasterVideoResourcesRequest();
describeCasterVideoResourcesRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
DescribeCasterVideoResourcesResponse response = client.getAcsResponse(describeCasterVideoResourcesRequest);

// DeleteCasterVideoResource: Deletes a video source.
DeleteCasterVideoResourceRequest deleteCasterVideoResourceRequest = new DeleteCasterVideoResourceRequest();
deleteCasterVideoResourceRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
deleteCasterVideoResourceRequest.setResourceId("LIVEPRODUCER_POST-cn-0pp123h****");
DeleteCasterVideoResourceResponse response = client.getAcsResponse(deleteCasterVideoResourceRequest);

    3. Edit components.

      Description

      Configure components that are used to produce the output content. Supported components include text and images.

      API operations

      Item

      Description

      AddCasterComponent

      Adds a component.

      ModifyCasterComponent

      Modifies a component.

      DescribeCasterComponents

      Queries components.

      DeleteCasterComponent

      Deletes a component.

      Note

      You must configure the following information about components:

      • If the component is text, set the properties such as text content, font proportion, and colors.

      • If the component is an image, specify the ID of the image component.

      Sample code

      // AddCasterComponent: Adds a component.
JSONObject componentLayer = new JSONObject();
componentLayer.put("HeightNormalized", 0.2);
componentLayer.put("WidthNormalized", 0.2);
JSONArray positionNormalized = new JSONArray();
positionNormalized.add("0.3");
positionNormalized.add("0.3");
componentLayer.put("PositionNormalized", positionNormalized);
componentLayer.put("PositionRefer", "topLeft");
JSONObject textLayerContent = new JSONObject(); // Create the textLayerContent component.
textLayerContent.put("Text", text);
textLayerContent.put("Color", 0xff0000);
textLayerContent.put("FontName", "KaiTi");
textLayerContent.put("SizeNormalized", 0.3F);
textLayerContent.put("BorderWidthNormalized", 0.3F);
textLayerContent.put("BorderColor", 0xff0000);
AddCasterComponentRequest addCasterComponntRequest = new AddCasterComponentRequest(); // Set the properties of the component.
addCasterComponntRequest.setCasterId(casterId);
addCasterComponntRequest.setLocationId(locationId);
addCasterComponntRequest.setComponentName(componentName);
addCasterComponntRequest.setComponentType("text");
addCasterComponntRequest.setEffect(effect);
addCasterComponntRequest.setComponentLayer(componentLayer.toJSONString());
addCasterComponntRequest.setTextLayerContent(textLayerContent.toJSONString());
AddCasterComponentResponse response = client.getAcsResponse(addCasterComponntRequest);

// ModifyCasterComponent: Modifies a component.
JSONObject componentLayer = new JSONObject();
componentLayer.put("HeightNormalized", 0.6);
componentLayer.put("WidthNormalized", 0.6);
JSONArray positionNormalized = new JSONArray();
positionNormalized.add("0.3");
positionNormalized.add("0.3");
componentLayer.put("PositionNormalized", positionNormalized);
componentLayer.put("PositionRefer", "topLeft");
JSONObject textLayerContent = new JSONObject();// Create the textLayerContent component.
textLayerContent.put("Text", text);
textLayerContent.put("Color", 0xff0000);
textLayerContent.put("FontName", "KaiTi");
textLayerContent.put("SizeNormalized", 0.3F);
textLayerContent.put("BorderWidthNormalized", 0.3F);
textLayerContent.put("BorderColor", 0xff0000);
ModifyCasterComponentRequest modifyCasterComponentRequest = new ModifyCasterComponentRequest(); // Modifies the properties of the component.
modifyCasterComponentRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterComponentRequest.setComponentId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterComponentRequest.setComponentName("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterComponentRequest.setComponentType("text"); // The text type.
modifyCasterComponentRequest.setEffect("none"); // No effects.
modifyCasterComponentRequest.setComponentLayer(componentLayer.toJSONString());
modifyCasterComponentRequest.setTextLayerContent(textLayerContent.toJSONString());
ModifyCasterComponentResponse response = client.getAcsResponse(modifyCasterComponentRequest);

// DescribeCasterComponents: Queries components.
DescribeCasterComponentsRequest describeCasterComponentsRequest= new DescribeCasterComponentsRequest();
describeCasterComponentsRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
DescribeCasterComponentsResponse response = iAcsClient.getAcsResponse(describeCasterComponentsRequest);

// DeleteCasterComponent: Deletes a component.
DeleteCasterComponentRequest deleteCasterComponentRequest = new DeleteCasterComponentRequest();
deleteCasterComponentRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
deleteCasterComponentRequest.setComponentId("LIVEPRODUCER_POST-cn-0pp123h****");
DeleteCasterComponentResponse response = client.getAcsResponse(deleteCasterComponentRequest);

    4. Edit layouts.

      Description

      Configure the layouts of the output content. You can customize screens and their locations. Up to four screens can be created in a layout.

      API operations

      Item

      Description

      AddCasterLayout

      Adds a layout.

      ModifyCasterLayout

      Modifies a layout.

      DescribeCasterLayouts

      Queries layouts.

      DeleteCasterLayout

      Deletes a layout.

      videoLayer

      Specifies the properties of the layout.

      audioLayer

      Specifies the audio information.

      blendList

      Specifies the locations of video sources.

      mixList

      Specifies the locations of audio tracks.

      Sample code

      JSONObject componentLayer = new JSONObject();
componentLayer.put("HeightNormalized", 0.6);
componentLayer.put("WidthNormalized", 0.6);
JSONArray positionNormalized = new JSONArray();
positionNormalized.add("0.3");
positionNormalized.add("0.3");
componentLayer.put("PositionNormalized", positionNormalized);
componentLayer.put("PositionRefer", "topLeft");
JSONObject imageLayerContent = new JSONObject(); // Create the imageLayerContent component.
imageLayerContent.put("MaterialId", "materailId");
AddCasterComponentRequest addCasterComponntRequest = new AddCasterComponentRequest(); // Set the properties of the component.
addCasterComponntRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterComponntRequest.setLocationId("RC01"); // The location ID that is associated with the component.
addCasterComponntRequest.setComponentName("LIVEPRODUCER_POST-cn-0pp123h****");
addCasterComponntRequest.setComponentType("image"); // The image type.
addCasterComponntRequest.setEffect("none"); // No effects.
addCasterComponntRequest.setComponentLayer(componentLayer.toJSONString());
addCasterComponntRequest.setImageLayerContent(imageLayerContent.toJSONString());
AddCasterComponentResponse response = client.getAcsResponse(addCasterComponntRequest);

// ModifyCasterLayout: Modifies a layout.
ModifyCasterLayoutRequest modifyCasterLayoutRequest = new ModifyCasterLayoutRequest();
modifyCasterLayoutRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
modifyCasterLayoutRequest.setLayoutId("LIVEPRODUCER_POST-cn-0pp123h****");
List videoLayersList = new ArrayList(); // The video layer.
ModifyCasterLayoutRequest.VideoLayer videoLayer1 = new ModifyCasterLayoutRequest.VideoLayer();
videoLayer1.setHeightNormalized(0.5F);
videoLayer1.setWidthNormalized(0.5F);
videoLayer1.setPositionRefer("topLeft");
videoLayer1.setPositionNormalizeds(Arrays.asList(new Float[]{0F, 0F}));
videoLayersList.add(videoLayer1);
ModifyCasterLayoutRequest.VideoLayer videoLayer2 = new ModifyCasterLayoutRequest.VideoLayer();
videoLayer2.setHeightNormalized(0.5F);
videoLayer2.setWidthNormalized(0.5F);
videoLayer2.setPositionRefer("topLeft");
videoLayer2.setPositionNormalizeds(Arrays.asList(new Float[]{0.5F, 0F}));
videoLayersList.add(videoLayer2);
ModifyCasterLayoutRequest.VideoLayer videoLayer3 = new ModifyCasterLayoutRequest.VideoLayer();
videoLayer3.setHeightNormalized(0.5F);
videoLayer3.setWidthNormalized(0.5F);
videoLayer3.setPositionRefer("topLeft");
videoLayer3.setPositionNormalizeds(Arrays.asList(new Float[]{0.2F, 0.5F}));
videoLayersList.add(videoLayer3);
modifyCasterLayoutRequest.setVideoLayers(videoLayersList);
List audioLayerList = new ArrayList();
ModifyCasterLayoutRequest.AudioLayer audioLayer1 = new ModifyCasterLayoutRequest.AudioLayer(); // The audio layer.
audioLayer1.setVolumeRate(1F);
audioLayer1.setValidChannel("all");
audioLayerList.add(audioLayer1);
ModifyCasterLayoutRequest.AudioLayer audioLayer2 = new ModifyCasterLayoutRequest.AudioLayer();
audioLayer2.setVolumeRate(1F);
audioLayer2.setValidChannel("all");
audioLayerList.add(audioLayer2);
ModifyCasterLayoutRequest.AudioLayer audioLayer3 = new ModifyCasterLayoutRequest.AudioLayer();
audioLayer3.setVolumeRate(1F);
audioLayer3.setValidChannel("all");
audioLayerList.add(audioLayer3);
modifyCasterLayoutRequest.setAudioLayers(audioLayerList);
modifyCasterLayoutRequest.setBlendLists(Arrays.asList(new String[]{"RV01", "RV02", "RV03"}));
modifyCasterLayoutRequest.setMixLists(Arrays.asList(new String[]{"RV01", "RV02", "RV03"}));
ModifyCasterLayoutResponse response = client.getAcsResponse(modifyCasterLayoutRequest);

// DescribeCasterLayout: Queries layouts.
DescribeCasterLayoutsRequest request = new DescribeCasterLayoutsRequest();
request.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
DescribeCasterLayoutsResponse response = client.getAcsResponse(request);

// DescribeCasterLayout: Deletes a layout.
DeleteCasterLayoutRequest deleteCasterLayoutRequest = new DeleteCasterLayoutRequest();
deleteCasterLayoutRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
deleteCasterLayoutRequest.setLayoutId("LIVEPRODUCER_POST-cn-0pp123h****");
DeleteCasterLayoutResponse response = client.getAcsResponse(deleteCasterLayoutRequest);

    5. Start a production studio.

      Sample code

      After you create and configure a production studio, you can start the production studio. This way, relevant audio and video processing tasks are started.

      Prerequisites

      The settings of the production studio are configured, including a domain name and the resolution of output videos.

      API operations

      Item

      Description

      StartCaster

      Starts a production studio.

      CasterID

      Specifies the ID of the production studio that you want to start.

      Note

      After you start the production studio, the information about the PVW and PGM scenes is returned, including the scene IDs and information about live streams. You can specify a scene by scene ID.

      Sample code

      StartCasterRequest request = new StartCasterRequest();
request.setCasterId("test");
StartCasterResponse response = client.getAcsResponse(request);
System.out.println(new Gson().toJson(response));

    6. Update a scene.

      Description

      After the production studio is started, you can apply the configured layout or components to a specific scene.

      Prerequisites

      • A layout or a component is configured.

      • A specific scene is created and enabled.

      API operations

      Item

      Description

      UpdateCasterSceneConfig

      Updates the configurations of a scene.

      DeleteCasterSceneConfig

      Deletes the configurations of a scene.

      CasterID

      Specifies the ID of the production studio.

      SceneID

      Specifies the ID of the scene.

      Sample code

      // UpdateCasterSceneConfig: Updates the configurations of a scene.
UpdateCasterSceneConfigRequest updateCasterSceneConfigRequest = new UpdateCasterSceneConfigRequest();
updateCasterSceneConfigRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
updateCasterSceneConfigRequest.setSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
updateCasterSceneConfigRequest.setComponentIds(componentList);
UpdateCasterSceneConfigResponse response = client.getAcsResponse(updateCasterSceneConfigRequest);

// DeleteCasterSceneConfig: Deletes the configurations of a scene.
DeleteCasterSceneConfigRequest deleteCasterSceneConfigRequest = new DeleteCasterSceneConfigRequest();
deleteCasterSceneConfigRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
deleteCasterSceneConfigRequest.setType("Component") // Clear the component configurations of a scene.
DeleteCasterSceneConfigResponse response = client.getAcsResponse(deleteCasterSceneConfigRequest);

    7. Switch from PVW to PGM.

      Description

      After the production studio is started, you can apply the layout settings of a PVW scene to a PGM scene.

      Prerequisites

      • A PVW scene is created and enabled.

      • A PGM scene is created and enabled.

      API operations

      Item

      Description

      CopyCasterSceneConfig

      Updates the configurations of a scene.

      CasterID

      Specifies the ID of the production studio.

      FromSceneID

      Specifies the ID of the PVW scene.

      ToSceneID

      Specifies the ID of the PGM scene.

      Sample code

      // CopyCasterSceneConfig: Switches scenes.
CopyCasterSceneConfigRequest copyCasterSceneConfigRequest = new CopyCasterSceneConfigRequest();
copyCasterSceneConfigRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
copyCasterSceneConfigRequest.setFromSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
copyCasterSceneConfigRequest.setToSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
CopyCasterSceneConfigResponse response = client.getAcsResponse(copyCasterSceneConfigRequest);

    8. Enable and disable the PVW mode.

      Description

      After the production studio is started, you can enable and disable the PVW mode to control the PVW scene. After the PVW scene is disabled, changes on layouts and video sources can be directly applied to the PGM scene.

      Prerequisites

      A PVW scene is created.

      API operations

      Item

      Description

      StartCasterScene

      Enables the PVW mode.

      StopCasterScene

      Disables the PVW mode.

      CasterID

      Specifies the ID of the production studio.

      SceneID

      Specifies the ID of the PVW scene.

      Sample code

      // StartCasterScene: Enables the PVW mode.
StartCasterSceneRequest startCasterSceneRequest = new StartCasterSceneRequest();
startCasterSceneRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
startCasterSceneRequest.setSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
StartCasterSceneResponse response = client.getAcsResponse(startCasterSceneRequest);

// StopCasterScene: Disables the PVW mode.
StopCasterSceneRequest stopCasterSceneRequest = new StopCasterSceneRequest();
stopCasterSceneRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
stopCasterSceneRequest.setSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
StopCasterSceneResponse response = client.getAcsResponse(stopCasterSceneRequest);

    9. Switch to a standby resource and switch back to the live stream.

      Description

      After the production studio is started, you can switch to a standby resource in the PGM scene. You can also switch back to the live stream.

      Prerequisites

      • The production studio is started.

      • The ID of the standby resource is specified.

      API operations

      Item

      Description

      EffectCasterUrgent

      Switches to the standby resource.

      SetCasterSceneConfig

      Switches back to the live stream.

      CasterID

      Specifies the ID of the production studio.

      SceneID

      Specifies the ID of the PGM scene.

      Sample code

      // StartCasterScene: Switches to the standby resource.
EffectCasterUrgentRequest effectCasterUrgentRequest = new EffectCasterUrgentRequest();
effectCasterUrgentRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
effectCasterUrgentRequest.setSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
EffectCasterUrgentResponse response = client.getAcsResponse(effectCasterUrgentRequest);

// SetCasterSceneConfig: Switches back to the live stream.
SetCasterSceneConfigRequest setCasterSceneConfigRequest = new SetCasterSceneConfigRequest();
setCasterSceneConfigRequest.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
setCasterSceneConfigRequest.setSceneId("LIVEPRODUCER_POST-cn-0pp123h****");
setCasterSceneConfigRequest.setLayoutId(null); // If you want to exit from the standby resource, enter null. If you want to switch to a specific layout, enter the ID of the specific layout.
SetCasterSceneConfigResponse response = client.getAcsResponse(setCasterSceneConfigRequest);

    10. Stop a production studio.

      Description

      After a production studio is started, you can stop the production studio and its audio and video processing tasks.

      Prerequisites

      The production studio is started.

      API operations

      Item

      Description

      StopCaster

      Stops a production studio.

      CasterID

      Specifies the ID of the production studio.

      Sample code

      // StopCaster: Stops a production studio.
StopCasterRequest request = new StopCasterRequest();
request.setCasterId("LIVEPRODUCER_POST-cn-0pp123h****");
StopCasterResponse response = client.getAcsResponse(request);