Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

  • Core Products
  • Add-Ons
  • Extensions Marketplace

    Update service

    Real-Time STT supports the update command, which allows modification of parameters without stopping and restarting the service. For example, when transcription is enabled for a specified host only, and this host disconnects and rejoins the channel with a different UID, the Real-Time STT service needs to subscribe to the new UID and transcribe their audio. The update command can help resolve this problem.

    The update command scope includes the following:

    • Update transcription languages.
    • Update UIDs of specified hosts whose audio needs to be transcribed.
    • Switch between transcribing all hosts and a specified host.

    Prerequisites​

    To follow this procedure, you must:

    • Have a valid Agora Account.

    • Have a valid Agora project with an app ID and a temporary token or a token server. For details, see Agora account management.

    • Have a computer with access to the internet. If your network has a firewall, follow the steps in Firewall requirements.

    • Join an RTC channel as a host and start streaming.

    • Make sure Real-Time STT is enabled for your app.

    Implementation​

    Follow the API call sequence from the REST Quickstart.

    Request examples​

    • Update the transcription language:


      _7
      curl --location -g --request PATCH 'https://api.agora.io/v1/projects/{{appId}}/rtsc/speech-to-text/tasks/{{taskId}}?builderToken={{tokenName}}&sequenceId=1&updateMask=languages' \
      _7
      --header 'Content-Type: application/json'
      _7
      --data '{
      _7
      "languages": [
      _7
      "<YourTranscribeLanguages>" // Max can configure 2 languages. e.g. "en-US", "ru-RU". If set 2 languages, STT service will automaticly enable Language Detection feature it will cause addtional cost.
      _7
      ],
      _7
      }'

    • Update the UID


      _7
      curl --location -g --request PATCH 'https://api.agora.io/v1/projects/{{appId}}/rtsc/speech-to-text/tasks/{{taskId}}?builderToken={{tokenName}}&sequenceId=1&updateMask=rtcConfig.subscribeAudioUids' \
      _7
      --header 'Content-Type: application/json'
      _7
      --data '{
      _7
      "rtcConfig": {
      _7
      "subscribeAudioUids": "[uint]}", // ["all"] or ["uid1", "uid2", "uid3"], "all" means service channel.
      _7
      },
      _7
      }'

    Response examples​

    • Success


      _5
      {
      _5
      "taskId": "String", // taskId
      _5
      "createTs": number, // create ts
      _5
      "status": enum(STATUS) // task status: IDLE, PREPARING, IN_PROGRESS, STOPPING, STOPPED
      _5
      }

    • Failure


      _3
      {
      _3
      "message": string // error reason
      _3
      }

    Notice​

    • Calling update requires at least 5-second intervals, specifically:
      • After calling start, the app needs to wait at least 5 seconds to call the update command.
      • After calling update, the app needs to wait at least 5 seconds before calling update again.
      • There is no interval limitation for calling update with query and stop commands.
    • When updated, the new parameter fully replaces the old parameter, unless the old parameter is masked with updateMask. For example, say the audio of hosts with UID 100 and 200 is being transcribed. The host with the UID 200 disconnects and rejoins with the new UID 300. The update command needs to use "subscribeAudioUids": "[ "100", "300" ]. If it uses only "subscribeAudioUids": "[ "300" ], then only the UID 300 host's audio will be transcribed. The languages configuration will not be updated.
    • If languages and host UIDs are updated together, pass in "updateMask=languages,rtcConfig.subscribeAudioUids".
    • sequenceId should increase by 1 for each request.
    vundefined