go-ring

go-ring

A Go client for Ring authentication, device discovery and controls, recordings, and persistent signaling sessions.

The customer guides walk through authentication, device operations, live sessions, SDP and ICE, push notifications, and cloud playback alongside the generated API reference.

The client supports PTZ over signaling WebSockets. Paired replays are labeled synthetic; inherited sanitized captures without source provenance are kept as historical regressions, not current provider evidence.

Install

Requires Go 1.24 or later.

go get github.com/portpowered/go-ring@v0.5.0

Examples

The examples below cover authentication, device discovery, controls, and a live WebRTC session.

1. Authenticate

Create a login session, request a verification code, and complete the exchange.

client, err := ring.NewClient()
if err != nil { return err }
login, err := client.NewLoginSession(ring.LoginSessionRequest{Username: username, Password: password})
if err != nil { return err }
defer login.Close()

// Request a verification code for the user.
if err := login.Request2FACode(ctx); err != nil { return err }

// Read the code from the user's verification channel.
otpCode := os.Getenv("RING_OTP_CODE")
tokens, err := login.Authenticate(ctx, ring.CompleteLoginRequest{OTPCode: otpCode})
if err != nil { return err }
accessToken := tokens.AccessToken
auth := ring.AuthContext{AccessToken: accessToken, HardwareID: login.HardwareID()}

Token exchange example.

2. List devices

Pass the resulting authentication context to each request.

client, err := ring.NewClient()
if err != nil { return err }

devices, err := client.ListDevices(ctx, ring.ListDevicesRequest{Auth: auth})
if err != nil { return err }
for _, device := range devices.Devices {
    fmt.Printf("%s: %s (%s)\n", device.ID, device.Name, device.Kind)
    if device.Supports(ringapimodels.DeviceCapabilityPtzPanStep) {
        fmt.Println("  supports step pan control")
    }
}

Each device reports capabilities confirmed by its inventory response. An absent capability means support is unknown, so the server remains the final authority for a control request. See the device operations guide.

enumerate-devices example.

3. Reboot a device

client, err := ring.NewClient()
if err != nil { return err }

if err := client.RebootDevice(ctx, ring.DeviceIDRequest{Auth: auth, DeviceID: deviceID}); err != nil {
    return err
}

reboot-device example.

4. Play a chime test sound

This command requires a chime device.

client, err := ring.NewClient()
if err != nil { return err }

if err := client.TestSound(ctx, ring.TestSoundRequest{
    Auth:     auth,
    DeviceID: chimeID,
    Sound:    ringapimodels.SoundKindDing,
}); err != nil {
    return err
}

Chime sound example.

5. Establish a live WebRTC session

Create a local WebRTC offer, start a device session with it, then apply the answer to the same peer connection.

// create new peer connection
pc, err := webrtc.NewPeerConnection(webrtc.Configuration{})
if err != nil { return err }
defer pc.Close()
if _, err := pc.AddTransceiverFromKind(webrtc.RTPCodecTypeVideo,
    webrtc.RtpTransceiverInit{Direction: webrtc.RTPTransceiverDirectionRecvonly}); err != nil {
    return err
}
pc.OnTrack(func(track *webrtc.TrackRemote, _ *webrtc.RTPReceiver) {
    for {
        if _, _, err := track.ReadRTP(); err != nil { return }
    }
})
offer, err := pc.CreateOffer(nil)
if err != nil { return err }
gathered := webrtc.GatheringCompletePromise(pc)
if err := pc.SetLocalDescription(offer); err != nil { return err }
select {
case <-gathered:
case <-ctx.Done(): return ctx.Err()
}


client, err := ring.NewClient()
if err != nil { return err }

// establish persistent connection session
conn, err := client.OpenSignaling(ctx, ring.OpenSignalingRequest{Auth: auth})
if err != nil { return err }
defer conn.Close()

// establish device session
session, err := conn.StartDeviceSession(ctx, ring.StartDeviceSessionRequest{
    DeviceID:     deviceID,
    Offer:        ring.SessionDescription{Type: ring.SDPTypeOffer, SDP: pc.LocalDescription().SDP},
    VideoEnabled: true,
    ICEMode:      ring.ICENonTrickle,
})

if err != nil { return err }
defer session.Close()
if err := pc.SetRemoteDescription(webrtc.SessionDescription{
    Type: webrtc.SDPTypeAnswer,
    SDP:  session.Answer().SDP,
}); err != nil { return err }

This uses non-trickle ICE; the full rtc_stream example also shows trickle ICE, remote candidates, and session events. The library handles signaling, while your application owns the Pion peer and media rendering.

6. Move the camera and stop

Once StartDeviceSession returns you can move the camera around if your camera supports it.

// move around
_, err := session.PanContinuous(ctx, ring.PanContinuousRequest{
    Direction: ring.PanRight,
    Speed:     0.5, // normalized range: 0 to 1
})
if err != nil { return err }
select {
case <-time.After(time.Second):
case <-ctx.Done():
}
stopCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
// stop the move.
_, err = session.StopPTZ(stopCtx, ring.StopPTZRequest{Axis: ring.PanAxis})
return err

For TiltContinuous, stop with ring.TiltAxis. See the pan and tilt example.

More examples

API reference

Browse the generated Ring API reference.

CLI quick start

The diagnostic CLI exercises common workflows:

git clone https://github.com/portpowered/go-ring.git
cd go-ring/cmd/go-ring
go build -o go-ring .
./go-ring auth login
./go-ring devices list
./go-ring siren <device-id> on
./go-ring snapshot <device-id> --output camera.jpg
./go-ring view <device-id> --continuous
./go-ring events watch <device-id> --duration 60s

See the diagnostic CLI guide for commands and troubleshooting.

Supported operations

Client handles authentication and HTTP requests and can be reused across accounts. Each returned connection owns its own lifetime. SignalingConnection owns the persistent signaling socket; it can start live device sessions, playback sessions, and push subscriptions. Close the returned connection or session when its work ends. Client.Close remains for source compatibility and does not close those objects.

References

Reverse engineering resources

• Ring API and customer guides
• Reverse engineering process
• Ring OpenAPI HTTP contracts and Ring AsyncAPI signaling/JSON-RPC contracts

Internal development resources

• Architecture and ownership
• Public model schema
• Recording formats and verification order
• Replay, unit, and live integration coverage
• API replay recordings
• Contributing

Issues

Please open an issue for a reproducible bug or unsupported device behavior.

Compatibility and license

Go implementation: Apache-2.0, see LICENSE.