Run the quick-start example

go/examples/quick-start in the whip-sdk repository is a ready-to-run WHIP Service example. It supports two tests:

• Business media test: after the device connects, the service continuously sends test audio and test images to confirm that the device can receive audio and video.
• Echo test: the service returns the audio and video sent by the device to confirm both sending and receiving.

The example implements token verification, WHIP session creation and deletion, and shutdown cleanup so you can validate the complete integration flow.

Prerequisites

• A WHIP service enabled as described in Architecture and integration, with a confirmed service_name, Access Key ID, Regions, and Echo query
• An Ed25519 key pair whose public key and regional endpoint are registered with TiRTC; keep the private key on the business server
• Linux x86_64 and Go 1.22 or later
• whip-sdk from tangeai/whip-sdk and a matching native release from the TiRTC SDK download page, installed as described in whip-sdk/clib/README.md
• A TiRTC device ID and Device Secret Key

Contact TiRTC technical support if you do not yet have the registration values, SDK, or matching native release.

Start the example

Set the token-verification values confirmed during service registration:

export TIRTC_ACCESS_KEY='<registered Access Key ID>'
export TIRTC_PUBLIC_KEY='<registered Ed25519 public key paired with the signing key>'

• TIRTC_ACCESS_KEY identifies the registered token-verification key.
• TIRTC_PUBLIC_KEY verifies connection tokens. It may be PEM, Base64, Base64URL, or hexadecimal encoded.

git clone https://github.com/tangeai/whip-sdk.git
cd whip-sdk/go/examples/quick-start
go run -tags tirtc_clib . \
  -listen :8080 \
  -service quick-start \
  -access-key "$TIRTC_ACCESS_KEY" \
  -public-key "$TIRTC_PUBLIC_KEY" \
  -candidate 203.0.113.10

Use your registered service name. Omit -candidate unless the service must advertise a different public address.

The service endpoint may use HTTPS or HTTP; some devices may require HTTP access. Forward POST /whip, normal-session DELETE /whip/resource/{session_id}, and Echo-session DELETE /whip/echo/resource/{session_id} to the application.

Obtain connection parameters

go/examples/whip-token-signer in the whip-sdk repository generates a peer_id and reusable delegation token for a device. It does not require the native TiRTC libraries:

export TIRTC_PRIVATE_KEY='<Ed25519 private key paired with TIRTC_PUBLIC_KEY>'

cd whip-sdk/go/examples
go run ./whip-token-signer \
  -service quick-start \
  -access-key "$TIRTC_ACCESS_KEY" \
  -private-key "$TIRTC_PRIVATE_KEY" \
  -device-id your_device_id \
  -query '_tg_mode=echo'

Replace quick-start with the registered service name and provide the authorized device ID. Use _tg_mode=echo shown above for the Echo test. The command prints:

{
  "peer_id": "whips://quick-start?_tg_mode=echo",
  "token": "<signed-token>"
}

Set ECHO_PEER_ID and CONNECT_TOKEN to these output values for the next step. Normal and Echo connections use the same endpoint.

This tool is for development and integration testing. In production, the business server must authorize the device before using the same issuing API to return a peer_id and token. Keep the private key on the business server and out of devices and logs.

Test with the device tool

See tangeai/tirn-probe-device for the source and complete instructions. Obtain the matching SDK from the TiRTC SDK download page, then build the tool:

git clone https://github.com/tangeai/tirn-probe-device.git
cd tirn-probe-device
./script/build.sh --sdk-dir /absolute/path/to/tirtc-sdk

The build script supports native macOS arm64 and Linux x86_64 builds; it does not cross-compile. Then run:

./build/linux-x86_64/tirn_probe_device media \
  --device-id your_device_id \
  --device-secret-key your_device_secret_key \
  --peer-id "$ECHO_PEER_ID" \
  --token "$CONNECT_TOKEN" \
  --audio-output /tmp/tirn-probe-echo.pcm \
  --duration-sec 10

The media command needs no camera, microphone, or external media file. It sends built-in 440 Hz PCM audio and a bundled JPEG test frame, then receives audio and video returned by the Echo service. It passes when all four send and receive counters are greater than zero. The optional --audio-output argument saves received audio as raw 8 kHz, 16-bit, mono PCM.

tirn_probe_device is an integration tool, not a production device SDK or part of the WHIP Service.

The same token may be reused until expiry. The TiRTC SDK and platform handle service discovery and routing automatically.

Additional examples:

• whip-sdk/go/examples/gin-service: Gin authentication middleware, Echo selection, and a normal business handler
• whip-sdk/go/examples/observable-service: structured logging, Stats(), observers, and /metrics

Common failures include invalid credentials or query (401/403), an oversized SDP Offer (413), an incorrect media type (415), and unreachable UDP or candidate addresses after SDP succeeds.