oxvif

Async ONVIF client for IP cameras (Profile S/T/G) in Rust — discovery, PTZ, media, imaging & events.

UDP multicast ──► discovery::probe() ──► Vec<DiscoveredDevice>
                                                  │
                                                  ▼ XAddr
                      OnvifSession ─── caches service URLs, delegates every call
                           │
SOAP/HTTP ──────►  OnvifClient ──► Device    (capabilities, hostname, NTP, reboot)
                               ──► Media1    (profiles, RTSP/snapshot URIs, video + audio configs)
                               ──► Media2    (H.265, metadata, audio, video source modes)
                               ──► PTZ       (move, stop, presets, home, status, configurations, nodes)
                               ──► Imaging   (brightness, contrast, exposure, IR cut, focus move/stop)
                               ──► OSD       (create, read, update, delete on-screen display elements)
                               ──► Events    (subscribe, pull, renew, unsubscribe, continuous stream)
                               ──► Recording (list, create/delete recordings and recording jobs)
                               ──► Search    (find recordings by time/scope)
                               ──► Replay    (RTSP URI for playback)

• Async-first (tokio + reqwest)
• WS-Security UsernameToken with PasswordDigest (ONVIF Profile S §5.12)
• HTTP Digest Authentication (RFC 7616, ONVIF Profile T §7.1)
• WS-Discovery via UDP multicast (239.255.255.250:3702)
• Mockable transport, plus a built-in mock ONVIF device (mock / mock-server features) — unit-test client code without a real camera
• Metamorph (metamorph / metamorph-server features) — clone a real camera and replay it verbatim offline, serve the clone from a bound port, diff its response shapes, or skin a non-ONVIF device as ONVIF
• No unsafe code; pure Rust XML parsing via quick-xml
• Optional, scriptable device health check with parse-coverage detection (health feature), plus a conformance example that validates the parsers against real cameras
• Hundreds of unit + doc tests, including the in-process mock device, the health checks, and scrubbed real-camera regression captures

Quick start

Two ways to use oxvif — pick whichever suits your workflow.

OnvifSession — URL caching handled for you

use oxvif::{OnvifSession, OnvifError};

#[tokio::main]
async fn main() -> Result<(), OnvifError> {
    let session = OnvifSession::builder("http://192.168.1.100/onvif/device_service")
        .with_credentials("admin", "password")
        .with_clock_sync()   // syncs WS-Security timestamp with device clock
        .build()
        .await?;

    let profiles = session.get_profiles().await?;
    let uri = session.get_stream_uri(&profiles[0].token).await?;
    println!("RTSP: {}", uri.uri);
    Ok(())
}

OnvifClient — direct control, you manage service URLs

use oxvif::{OnvifClient, OnvifError};

#[tokio::main]
async fn main() -> Result<(), OnvifError> {
    let client = OnvifClient::new("http://192.168.1.100/onvif/device_service")
        .with_credentials("admin", "password");

    let caps = client.get_capabilities().await?;
    let media_url = caps.media.url.unwrap();

    let profiles = client.get_profiles(&media_url).await?;
    let uri = client.get_stream_uri(&media_url, &profiles[0].token).await?;
    println!("RTSP: {}", uri.uri);
    Ok(())
}

OnvifSession calls GetCapabilities once on build() and caches all service URLs — no URL arguments needed for individual methods. OnvifClient is stateless; you forward the URL yourself for full routing control.

Testing — drive a mock device, no camera needed

Enable the mock feature and point a client at a built-in, stateful mock ONVIF device — no network, no hardware. Ideal for unit tests.

[dev-dependencies]
oxvif = { version = "0.15", features = ["mock"] }

use std::sync::Arc;
use oxvif::{OnvifClient, mock::MockTransport};

#[tokio::test]
async fn talks_to_a_mock_camera() {
    let client = OnvifClient::new("http://mock")
        .with_transport(Arc::new(MockTransport::new()));

    client.set_hostname("lab-cam").await.unwrap();
    let h = client.get_hostname().await.unwrap();   // Set → Get round-trips
    assert_eq!(h.name.as_deref(), Some("lab-cam"));
}

Need a real bound port instead? The mock-server feature adds MockServer::start(). See Testing without a real camera for details.

Installation

[dependencies]
oxvif = "0.15"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Serde support (serde feature)

Enable the serde feature to derive Serialize + Deserialize on every response type in oxvif::types, plus the WS-Discovery result types (DiscoveredDevice, DiscoveryEvent) returned by discovery::probe and friends. This lets you expose them directly over a REST API (or persist them as JSON) without hand-cloning parallel structs.

[dependencies]
oxvif = { version = "0.15", features = ["serde"] }

// Any response type, straight to JSON — no shadow structs.
let profiles = session.get_profiles().await?;
println!("{}", serde_json::to_string_pretty(&profiles)?);

// …and back again, so they work as request bodies too.
let round_tripped: Vec<oxvif::MediaProfile> = serde_json::from_str(&json)?;

In a web handler that means the response type is the API type:

use axum::{Json, http::StatusCode};

async fn presets() -> Result<Json<Vec<oxvif::PtzPreset>>, StatusCode> {
    session.ptz_get_presets("Profile_1").await
        .map(Json)
        .map_err(|_| StatusCode::BAD_GATEWAY)
}

Field names are the Rust-native snake_case identifiers (no rename_all), and Deserialize is derived too, so the types also work as request bodies. The feature is opt-in: it pulls no new dependency and costs nothing when disabled.

OnvifSession

OnvifSession calls GetCapabilities once at construction, caches all service URLs internally, and exposes every operation as a one-liner — no URL parameters needed anywhere.

Building a session

use oxvif::{OnvifSession, OnvifError};

#[tokio::main]
async fn main() -> Result<(), OnvifError> {
    let session = OnvifSession::builder("http://192.168.1.100/onvif/device_service")
        .with_credentials("admin", "password")
        .with_clock_sync()   // syncs WS-Security timestamp with device clock
        .build()
        .await?;

    // Capabilities are already cached — no extra round-trip
    let caps = session.capabilities();

    let profiles = session.get_profiles().await?;
    let uri      = session.get_stream_uri(&profiles[0].token).await?;
    println!("RTSP: {}", uri.uri);

    let status = session.ptz_get_status(&profiles[0].token).await?;
    println!("Pan: {:?}  Tilt: {:?}", status.pan, status.tilt);

    Ok(())
}

Builder methods

Session accessors

OnvifSession delegates every OnvifClient method — the full method list is in the sections below (Device, Media, PTZ, Imaging, OSD, Events, Recording, Search, Replay).

OnvifClient

Stateless and cheaply cloneable — safe to wrap in Arc and share across threads. You manage the service URLs (obtained from get_capabilities() or get_services()), which gives you full control over per-call routing.

Constructors and builder methods

// Sync device clock before sending authenticated requests
let client = OnvifClient::new("http://192.168.1.100/onvif/device_service");
let dt = client.get_system_date_and_time().await?;
let client = client
    .with_credentials("admin", "secret")
    .with_utc_offset(dt.utc_offset_secs());

WS-Discovery

Find ONVIF cameras on your local network without knowing their IP addresses.

use std::time::Duration;
use oxvif::discovery;

let devices = discovery::probe(Duration::from_secs(3)).await;

for d in &devices {
    println!("Found: {}", d.endpoint);
    for addr in &d.xaddrs {
        println!("  XAddr: {addr}");          // use this as device_url
    }
    for scope in &d.scopes {
        println!("  Scope: {scope}");         // e.g. "onvif://www.onvif.org/name/Camera1"
    }
}

DiscoveredDevice fields:

probe returns an empty Vec on I/O errors; it never panics.

Device Service methods

get_capabilities() -> Result<Capabilities, OnvifError>

Retrieves all service endpoint URLs and feature flags. Always call this first.

let caps = client.get_capabilities().await?;

caps.device.url        // Device management service
caps.media.url         // Media service (profiles / stream URIs)
caps.ptz_url           // PTZ service
caps.events.url        // Events service
caps.imaging_url       // Imaging service
caps.analytics.url     // Analytics service
caps.media2_url        // Media2 service (None on many cameras — use GetServices)

caps.device.system.firmware_upgrade
caps.device.security.tls_1_2
caps.device.security.dot1x          // from Security/Extension/Extension
caps.media.streaming.rtp_rtsp_tcp
caps.events.ws_pull_point

SecurityCapabilities models all twelve members tt:SecurityCapabilities declares across its three levels. username_token is not among them and was removed in 0.15.0 — ONVIF declares that name only on the service-level type, so read it from device_get_service_capabilities().security.

Per-service capabilities — *_get_service_capabilities()

get_capabilities() answers which services exist and at what URL. Each service has its own GetServiceCapabilities answering what that service can do, and all nine are implemented:

let caps = client.device_get_service_capabilities().await?;

caps.security.tls1_2                 // Option<bool>
caps.security.max_users              // Option<u32>
caps.system.user_config_not_supported
caps.misc.map(|m| m.auxiliary_commands);  // what SendAuxiliaryCommand accepts

Every flag is Option<bool>, not bool. None means the device did not mention the attribute; Some(false) means it said no. The two are different answers, and collapsing them would defeat the reason for asking — a feature the firmware never described is not the same as one it declined. The device-level Capabilities from get_capabilities() uses bare bool and cannot make that distinction, which is why the two families are separate types.

List-valued attributes are the deliberate exception: they are Vec<_>, empty when absent, because for a list "absent" and "present but empty" both mean no items.

A few field types read wrong and are right:

• RecordingServiceCapabilities::max_recordings is f32 — xs:float in the schema, despite reading like a count.
• Media2ServiceCapabilities::webrtc is Option<u32>, a session count. Some(0) means WebRTC was described and no concurrent session is offered.
• RecordingServiceCapabilities::onboard_storage has a schema default of true which oxvif does not apply. Read onboard_storage.unwrap_or(true) if you want the schema's behaviour rather than the device's silence.

get_services() -> Result<Vec<OnvifService>, OnvifError>

Use as a fallback when caps.media2_url is None:

let caps = client.get_capabilities().await?;
let media2_url = caps.media2_url.clone().or_else(|| {
    client.get_services().await.ok()?
        .into_iter()
        .find(|s| s.is_media2())
        .map(|s| s.url)
});

OnvifSession does this for you for Profile G. Some cameras advertise the recording / search / replay services only via GetServices, not the GetCapabilities extension. OnvifSession::build fills any missing one from GetServices automatically, so get_recordings / search_recordings / get_replay_uri work on those devices without a manual fallback.

get_system_date_and_time() -> Result<SystemDateTime, OnvifError>

Retrieves the device clock. Compute the offset to keep WS-Security timestamps in sync.

let dt = client.get_system_date_and_time().await?;
let offset = dt.utc_offset_secs();   // device_utc − local_utc

get_device_info() -> Result<DeviceInfo, OnvifError>

let info = client.get_device_info().await?;
// info.manufacturer, info.model, info.firmware_version, info.serial_number

Hostname methods

NTP methods

system_reboot() -> Result<String, OnvifError>

Initiates a device reboot. Returns the device's informational message.

get_scopes() -> Result<Vec<String>, OnvifError>

Returns the device's scope URIs — strings that describe the device's name, location, hardware model, and capabilities (e.g. "onvif://www.onvif.org/name/Camera1"). Completes Profile S coverage.

let scopes = client.get_scopes().await?;
for s in &scopes {
    println!("{s}");
}

set_scopes(scopes) -> Result<(), OnvifError>

Replaces the device's configurable scopes with scopes: &[&str]. Fixed scopes the device reports as non-configurable are untouched.

set_system_date_and_time(req) -> Result<(), OnvifError>

Sets the clock — manual or NTP, with timezone and DST. Takes a SetDateTimeRequest; pair it with get_system_date_and_time().

User management

Network configuration

System & I/O

get_digital_inputs is the one method in this table that does not go to the device service. Digital inputs live on DeviceIO, so it takes that endpoint:

let caps = client.get_capabilities().await?;
let deviceio = caps.device_io.url.as_deref().unwrap();
for input in client.get_digital_inputs(deviceio).await? {
    println!("{} idle={}", input.token, input.idle_state);
}

A device that advertises no DeviceIO endpoint does not implement the operation. If caps.device_io.url is None, fall back to get_services() and look for OnvifService::is_device_io() — some firmware lists DeviceIO there and not in GetCapabilities. OnvifSession::get_digital_inputs() does both for you.

The three relay-output methods above genuinely are device-service operations, even though DeviceIO offers them too: deviceio.wsdl types those messages with the device service's own elements.

Media Service (Media1) methods

All Media1 methods use media_url from caps.media.url.

Profile management

Streaming

let profiles = client.get_profiles(&media_url).await?;

let rtsp = client.get_stream_uri(&media_url, &profiles[0].token).await?;
println!("RTSP: {}", rtsp.uri);

let snap = client.get_snapshot_uri(&media_url, &profiles[0].token).await?;
println!("Snapshot: {}", snap.uri);

Video source and encoder configurations

let mut enc = client.get_video_encoder_configuration(media_url, &token).await?;
if let Some(rc) = enc.rate_control.as_mut() {
    rc.bitrate_limit = 2048;   // 2 Mbps
}
client.set_video_encoder_configuration(media_url, &enc).await?;

Media2 methods

Media2 (ver20/media/wsdl) is the successor to Media1, with native H.265 support and a simplified encoder config structure. All Media2 methods use media2_url.

Media1 vs Media2 key differences

Media2 method reference

PTZ methods

All PTZ methods use ptz_url from caps.ptz_url. Coordinates use the ONVIF normalised range: pan/tilt [-1.0, 1.0], zoom [0.0, 1.0].

// Save current position
let token = client.ptz_set_preset(ptz_url, &profile, Some("Entrance"), None).await?;

// Query position
let status = client.ptz_get_status(ptz_url, &profile).await?;
println!("pan={:?} tilt={:?} zoom={:?} state={}",
    status.pan, status.tilt, status.zoom, status.pan_tilt_status);

PtzStatus fields: pan, tilt, zoom (Option<f32>), pan_tilt_status, zoom_status (String — "IDLE" or "MOVING"), utc_time (Option<String>), error (Option<String> — device fault description if any).

Preset tours

A preset tour is a stored guard tour: a named sequence of stops the camera walks unattended. Create an empty tour, fill it in, then start it.

use oxvif::{
    PtzPresetTour, PtzPresetTourDirection, PtzPresetTourOperation,
    PtzPresetTourPresetDetail, PtzPresetTourSpot, PtzPresetTourStartingCondition,
    PtzPresetTourState, PtzPresetTourStatus,
};

// What this device will accept — a stop outside these bounds comes back as a
// fault rather than being clamped.
let opts = client.ptz_get_preset_tour_options(ptz_url, &profile, None).await?;
println!("directions: {:?}", opts.starting_condition.directions);
println!("stay time:  {:?}", opts.tour_spot.stay_time);

let token = client.ptz_create_preset_tour(ptz_url, &profile).await?;

let tour = PtzPresetTour {
    token: Some(token.clone()),
    name: Some("Night sweep".into()),
    status: PtzPresetTourStatus {
        state: PtzPresetTourState::Idle,
        current_tour_spot: None,
    },
    auto_start: true,
    starting_condition: PtzPresetTourStartingCondition {
        random_preset_order: Some(false),
        recurring_time: Some(2),
        recurring_duration: None,
        direction: Some(PtzPresetTourDirection::Forward),
    },
    tour_spots: vec![PtzPresetTourSpot {
        preset_detail: PtzPresetTourPresetDetail::PresetToken("Preset_1".into()),
        speed: None,
        stay_time: Some("PT15S".into()),
    }],
};
client.ptz_modify_preset_tour(ptz_url, &profile, &tour).await?;

client
    .ptz_operate_preset_tour(ptz_url, &profile, &token, PtzPresetTourOperation::Start)
    .await?;

Two things about the types are worth knowing before you build one:

• PtzPresetTour::token is Option<String>. @token is optional on tt:PresetTour in the schema, unlike tt:PTZPreset/@token, so a device may return a tour without one and oxvif does not treat that as an error. You still need a token on the way in to every operation that names an existing tour.
• PtzPresetTourPresetDetail is an enum, not a struct. The schema member is an xs:choice — PresetToken, Home or an explicit Position, exactly one. Three Option fields would let you send two at once and get an unhelpful fault back.

PtzPresetTourState and PtzPresetTourDirection both carry an Unknown(String) variant. Both schema types end in Extended, so vendors do extend them, and an unrecognised value is carried rather than turning ptz_get_preset_tours into an Err.

Auxiliary commands — there are two of them

ptz_send_auxiliary_command(ptz_url, profile_token, data) and send_auxiliary_command(command) are different ONVIF operations that happen to share a name. The first is the PTZ service's, is scoped to a media profile, and returns the device's answer; the second is the Device service's and is not. Cameras that implement a wiper generally implement the PTZ one, so try that first.

The values a given camera accepts are vendor-namespaced, so oxvif does not model them as an enum — they are discoverable instead:

let advertised = client
    .device_get_service_capabilities()
    .await?
    .misc
    .map(|m| m.auxiliary_commands)
    .unwrap_or_default();
// e.g. ["tt:Wiper|On", "tt:Wiper|Off", "tt:IRLamp|On", "tt:IRLamp|Off", "tt:IRLamp|Auto"]

let answer = client
    .ptz_send_auxiliary_command(ptz_url, &profile, "tt:Wiper|On")
    .await?;

tt:AuxiliaryData has a schema maxLength of 128, which oxvif does not enforce: the device rejects an over-long value with a fault, and a client-side check would be a second source of truth that drifts from the firmware.

Audio Service methods

All audio methods use media_url from caps.media.url.

let sources = client.get_audio_sources(&media_url).await?;
println!("Audio inputs: {}", sources.len());

let mut enc = client.get_audio_encoder_configuration(&media_url, &token).await?;
enc.bitrate = 128;
client.set_audio_encoder_configuration(&media_url, &enc).await?;

AudioEncoderConfiguration fields: token, name, use_count, encoding (AudioEncoding), bitrate (kbps), sample_rate (kHz), channels (Option<u32>).

AudioEncoding variants: G711, G726, Aac, Other(String).

Imaging Service methods

All imaging methods use imaging_url from caps.imaging_url and require a video_source_token.

let mut s = client.get_imaging_settings(&imaging_url, &source_token).await?;
s.brightness = Some(70.0);
s.ir_cut_filter = Some("AUTO".into());
client.set_imaging_settings(&imaging_url, &source_token, &s).await?;

ImagingSettings fields: brightness, color_saturation, contrast, sharpness, focus_default_speed, wide_dynamic_range_level (Option<f32>); ir_cut_filter, white_balance_mode, exposure_mode, backlight_compensation, focus_mode, wide_dynamic_range_mode, image_stabilization_mode, tone_compensation_mode (Option<String>).

// Move focus to an absolute position
client.imaging_move(&imaging_url, &source_token,
    &FocusMove::Absolute { position: 0.5, speed: None }).await?;

// Start continuous autofocus sweep
client.imaging_move(&imaging_url, &source_token,
    &FocusMove::Continuous { speed: 0.3 }).await?;
client.imaging_stop(&imaging_url, &source_token).await?;

// Query focus state
let status = client.imaging_get_status(&imaging_url, &source_token).await?;
println!("focus={:?}  state={}", status.focus_position, status.focus_move_status);

OSD Service methods

On-screen display (OSD) elements overlay text or images on the video stream. All OSD methods use media_url from caps.media.url.

use oxvif::{OsdConfiguration, OsdPosition, OsdTextString};

// Create a date/time overlay in the upper-left corner
let osd = OsdConfiguration {
    token: String::new(),                           // empty = device assigns token
    video_source_config_token: vsc_token.clone(),
    type_: "Text".into(),
    position: OsdPosition { type_: "UpperLeft".into(), x: None, y: None },
    text_string: Some(OsdTextString {
        type_: "DateAndTime".into(),
        date_format: Some("MM/DD/YYYY".into()),
        time_format: Some("HH:mm:ss".into()),
        plain_text: None,
        font_size: Some(28),
        font_color: None,
        background_color: None,
        is_persistent_text: None,
    }),
    image_path: None,
};
let token = client.create_osd(&media_url, &osd).await?;
println!("Created OSD token: {token}");

// List all OSDs
let osds = client.get_osds(&media_url, None).await?;
for o in &osds {
    println!("[{}] type={} position={}", o.token, o.type_, o.position.type_);
}

OsdConfiguration fields: token, video_source_config_token, type_ ("Text" or "Image"), position (OsdPosition), text_string (Option<OsdTextString>), image_path (Option<String>).

OsdTextString fields: type_, plain_text, date_format, time_format (Option<String>), font_size (Option<u32>), font_color, background_color (Option<OsdColor>), is_persistent_text (Option<bool>). OsdColor carries x/y/z channel values, optional colorspace URI, and transparent level.

OsdOptions fields: max_osd (u32), types (Vec<String>), position_types (Vec<String>), text_types (Vec<String>).

Events Service methods

ONVIF Events use a pull-point subscription model. All operations start with events_url from caps.events.url.

// 1. Discover available topics
let props = client.get_event_properties(&events_url).await?;
for topic in &props.topics {
    println!("Topic: {topic}");    // e.g. "VideoSource/MotionAlarm"
}

// 2. Subscribe
let sub = client.create_pull_point_subscription(
    &events_url,
    None,           // filter: None = all topics
    Some("PT60S"),  // expire after 60 seconds
).await?;
println!("Subscription URL: {}", sub.reference_url);

// 3. Poll for events
let msgs = client.pull_messages(&sub.reference_url, "PT5S", 50).await?;
for m in &msgs {
    println!("[{}] {} — data={:?}", m.utc_time, m.topic, m.data);
}

// 4. Extend subscription
let new_time = client.renew_subscription(&sub.reference_url, "PT60S").await?;

// 5. Cancel
client.unsubscribe(&sub.reference_url).await?;

set_synchronization_point(subscription_url) asks the device to re-send the current state of every property topic on the subscription, so a client that just connected does not have to wait for the next change to learn it.

Continuous event stream

event_stream wraps the polling loop into an infinite async Stream — each item is one NotificationMessage. Use futures::StreamExt::take or a select! block to bound it, and call unsubscribe when done.

use futures::StreamExt as _;

let sub = client.create_pull_point_subscription(&events_url, None, Some("PT60S")).await?;
let mut stream = client.event_stream(&sub.reference_url, "PT5S", 10);

while let Some(Ok(msg)) = stream.next().await {
    println!("[{}] {} {:?}", msg.utc_time, msg.topic, msg.data);
}

PullPointSubscription fields:

NotificationMessage fields:

EventProperties fields:

Recording Service methods

Access and manage recordings stored on the device (NVR/DVR). Obtain recording_url from get_services() — namespace http://www.onvif.org/ver10/recording/wsdl.

Read operations

Write operations

// Create a recording and start a job
let config = RecordingConfiguration {
    source_name: "Camera1".into(),
    source_id: "src1".into(),
    location: "Front door".into(),
    description: "Front door camera".into(),
    content: String::new(),
    maximum_retention_time: "PT0S".into(),
};
let rec_token = client.create_recording(&recording_url, &config).await?;

let track_token = client.create_track(
    &recording_url, &rec_token, "Video", "Main stream"
).await?;

let job_config = RecordingJobConfiguration {
    recording_token: rec_token.clone(),
    mode: "Active".into(),
    priority: 1,
    source_token: "VideoSourceToken_0".into(),
};
let job_token = client.create_recording_job(&recording_url, &job_config).await?;
println!("Job token: {job_token}");

// Check job state
let state = client.get_recording_job_state(&recording_url, &job_token).await?;
println!("Active state: {}", state.active_state);

RecordingItem fields: token, source (RecordingSourceInformation), content, tracks (Vec<RecordingTrack>).

RecordingSourceInformation fields: source_id, name, location, description (String), address (Option<String> — network address of the source device).

RecordingTrack fields: token, track_type ("Video", "Audio", "Metadata"), description (String), data_from, data_to (Option<String> ISO-8601 — time bounds of recorded data in this track).

RecordingJob fields: token, recording_token, mode, priority (u32), source_token.

RecordingJobState fields: recording_token, active_state ("Active", "Idle", or device-specific string).

Search Service methods

Search through stored recordings. Obtain search_url from get_services() — namespace http://www.onvif.org/ver10/search/wsdl.

// Find all recordings, collect results, play back the first one
let search_url   = /* from get_services() */;
let replay_url   = /* from get_services() */;

let token = client.find_recordings(&search_url, None, "PT60S").await?;

let results = loop {
    let r = client.get_recording_search_results(&search_url, &token, 100, "PT5S").await?;
    if r.search_state == "Completed" { break r; }
};
client.end_search(&search_url, &token).await?;

for rec in &results.recording_information {
    println!("[{}] {} — {} to {}",
        rec.recording_token, rec.source_name,
        rec.earliest_recording.as_deref().unwrap_or("?"),
        rec.latest_recording.as_deref().unwrap_or("?"));
}

FindRecordingResults fields: search_state ("Queued", "Searching", "Completed"), recording_information (Vec<RecordingInformation>).

RecordingInformation fields: recording_token, source_name, earliest_recording, latest_recording, content, recording_status.

Replay Service methods

Stream a stored recording over RTSP. Obtain replay_url from get_services() — namespace http://www.onvif.org/ver10/replay/wsdl.

let uri = client.get_replay_uri(
    &replay_url,
    &rec.recording_token,
    "RTP-Unicast",
    "RTSP",
).await?;
println!("Playback: {uri}");
// Open in VLC: vlc "{uri}"

Health check (health feature)

Point it at a camera, get a Pass/Warn/Fail/Skip report with a Profile S/T/G verdict. A readable alternative to the official ONVIF Device Test Tool — pure library code over OnvifSession, no extra dependencies.

Try it now — no camera

cargo run --example healthcheck --features health,mock-server -- --mock

That starts a throwaway mock camera in-process and checks it. You get the real report format, and you can try --json and --baseline the same way:

ONVIF health check — http://127.0.0.1:27365/onvif/device
  31 pass · 0 warn · 0 fail · 1 skip   (20 ms total)

  [Connectivity]
    PASS connect                          5ms  GetCapabilities ok
    PASS get_device_info                  3ms  oxvif-mock MockCam-1080p fw 1.0.0

  [Time]
    PASS system_date_time                 3ms  skew 0s

  [Services]
    PASS get_services                     5ms  8 service(s)
    PASS service_caps_self_consistent     0ms  24 fact(s) cross-checked, no contradiction
    …

Then point it at your own camera:

cargo run --example healthcheck --features health -- \
    http://192.168.1.100/onvif/device_service admin password

In your own code

[dependencies]
oxvif = { version = "0.15", features = ["health"] }

use oxvif::health::HealthCheck;

#[tokio::main]
async fn main() {
    let report = HealthCheck::new("http://192.168.1.100/onvif/device_service")
        .with_credentials("admin", "password")
        .run()
        .await;

    // Human-readable: per-check status, timings, profile verdict.
    println!("{report}");

    // Or inspect it programmatically.
    for c in &report.checks {
        println!("{:?} {} — {}", c.status, c.id, c.detail);
    }
    println!("Profile S: {:?}", report.profiles.profile_s.verdict);

    if !report.ok() {
        std::process::exit(1);   // something actually failed
    }
}

HealthCheck::run() never returns an error — an unreachable device is a failing connect check, not an Err, so a batch run over a fleet cannot be derailed by one bad camera. Checks run concurrently and are read-only unless you opt in below.

Common options

report.to_json() / to_json_pretty() for CI; report.diff(&previous) for "what changed since the last run".

Want this with a GUI? OxDM — the ONVIF device manager built on this crate — drives the same HealthCheck from a Diagnostics tab: per-service Pass/Warn/Fail/Skip, the Profile S/T/G verdict, "save as baseline" plus an automatic diff on the next run, and batch runs across a fleet exportable as JSON or JUnit XML for CI. Everything below is the library underneath it, so the two report the same thing.

_{A batch run over a fleet — demonstrated in OxDM, which drives this crate's HealthCheck. The snapshot 291 KB / RTSP OK / replay URI OK badges are the liveness probes below: real bytes fetched, not an advertised URL echoed back.}

Reference — what each option actually does

Everything from here down is detail. The block above is enough to use it.

Active liveness probing (opt-in). By default the check only confirms the device answered each SOAP call. Enable with_liveness_probes(true) to also verify the results actually work:

let report = HealthCheck::new(url)
    .with_credentials("admin", "password")
    .with_liveness_probes(true)   // RTSP OPTIONS + snapshot bytes + real Profile G
    .run()
    .await;

With it on, get_stream_uri follows the RTSP URI with a non-destructive OPTIONS reachability probe, get_snapshot_uri fetches the bytes and validates them as a real image (rejecting a 0-byte body or an HTML error page returned with a 200), and the recording / search / replay checks genuinely exercise Profile G (recording search + replay-URI resolution) instead of reporting advertised-only presence. Off by default because these open extra RTSP/HTTP connections the read-only SOAP checks never touch.

Force-verifying undeclared services (opt-in). with_force_unsupported(true) goes after the opposite problem — a device that under-declares. For each profile-gating service the device doesn't advertise (Media2, recording / search / replay), it tries a few conventional service URLs (and the device endpoint itself) and calls the operation; one that answers is flagged as under-declared rather than counted as unsupported. Best-effort — vendors use non-standard paths, so a miss isn't proof of absence.

Raw-SOAP capture (opt-in, 0.13+). with_capture(true) records the raw request/response of every SOAP call that fails (a transport error or a SOAP Fault) into HealthReport::captured — the raw evidence for why a brand rejected a call, to pair with the structured CheckError. Off by default; successful (credential-bearing) requests are never stored, and stored requests have their WS-Security Password/Nonce blanked, so a capture carries no credential-derivation material. Each CapturedExchange keys on the SOAP action.

Structured facts (0.11+). For building a cross-brand conformance corpus, the report carries machine-readable facts alongside the human-readable strings:

• CheckResult::error — an optional CheckError on a failing check with a class (ErrorClass::SoapFault / Precondition / Parse / Http / InvalidArgument), the ONVIF subcode (e.g. ter:NotAuthorized), fault_code, reason, and verbatim detail. This lets you group the same fault across vendors by subcode instead of re-parsing free-text reasons, and separate genuine device faults from client-side preconditions.
• HealthReport::clock_skew_s — the numeric device-vs-local clock skew, the usual cause of spurious WS-Security auth failures.
• HealthReport::declared_profiles — the profiles the device self-declares via its scopes (e.g. ["S", "T", "G"]), read from GetScopes. Compare against the assessed profiles verdicts to flag "declares Profile G but replay/search fail".
• ProfileAssessment::profile_{s,t,g} — each a ProfileState { verdict, missing, unverified }. verdict is conformant / partial / unsupported / inconclusive; the last means required checks couldn't be tested (auth blocked / skipped) with nothing verified to fail — kept distinct from partial so "couldn't verify" is never read as "non-conformant". missing lists the ids that genuinely failed, unverified the ones that couldn't be tested. Profile T additionally requires media2 (Media2 advertised) and event_motion_topic (a motion-alarm topic), so a Profile-S-only device is not read as near-T.
• Category::Security / auth_enforcement — when credentials are supplied, a credential-free GetDeviceInformation probe checks the device actually enforces authentication. Serving device info anonymously is a security Warn; a rejection is a Pass.

Per-service capabilities, and the device against itself (0.15+). Nine service_caps_* checks ask each advertised service its own GetServiceCapabilities — Pass when it answers, Skip when the service is not advertised, Fail when it is advertised and refuses.

Then service_caps_self_consistent does the part no single call can: twenty-four attributes are stated twice by the device, once in the device-level GetCapabilities and again in a service's GetServiceCapabilities (twenty on Device — four network, five system, eleven security — three on Media streaming, one on Events). Everything else in a capability report is a claim with nothing to contradict it; these can be wrong rather than merely unknown, and a client trusting either source is guessing when they differ.

Only one direction is reported, and the asymmetry is the point:

The device-level Capabilities uses bare bool and so cannot distinguish "said no" from "did not say" — an omitted <tt:Network> element, which is legal and common, parses as four falses. true cannot come from absence, so only the first row is a certainty. The second is counted and shown in the detail (N stated only by the service) without a warning. Reading it as a finding would flag every terse but conformant camera; oxvif's own mock tripped it six times before its GetCapabilities was taught to state those blocks.

A contradiction is a Warn, not a Fail: the device works, and which source is right is not knowable from here — but it has to be visible.

Note: the health report shape changed in a breaking way in 0.12.0 (profiles became an object, verdicts/status.kind lowercase, elapsed_ms nullable). 0.11 output was provisional. See the CHANGELOG.

Parse coverage. The report also includes a Category::Coverage dimension: for a curated set of list operations it compares how many items the parser returned against how many item elements the device actually sent, and warns when the parser silently dropped data (the bug class where a wrong element name yields an empty result with no error). It catches list-emptying; it does not catch scalar field-defaulting — for that, validate against real hardware with the conformance example (the mirror of mock_server):

cargo run --example conformance --features mock -- devices.txt

It points oxvif at a list of real cameras, dumps each raw SOAP response, and prints a parsed summary so silent-parse mismatches stand out for review.

Error handling

All API methods return Result<T, OnvifError>:

pub enum OnvifError {
    Transport(TransportError),  // network / TLS / unexpected HTTP status
    Soap(SoapError),            // parse failure, missing field, or SOAP Fault
}

use oxvif::error::OnvifError;
use oxvif::soap::SoapError;
use oxvif::transport::TransportError;

match client.get_capabilities().await {
    Ok(caps) => { /* use caps */ }
    Err(OnvifError::Transport(TransportError::Http(e))) => eprintln!("Network: {e}"),
    Err(OnvifError::Transport(TransportError::HttpStatus { status, body })) => {
        eprintln!("HTTP {status}: {body}");
    }
    Err(OnvifError::Soap(SoapError::Fault { code, reason })) => {
        eprintln!("SOAP Fault [{code}]: {reason}");
    }
    Err(e) => eprintln!("Other: {e}"),
}

HTTP 500 is treated as Ok so the SOAP layer can parse the <s:Fault> detail.

Testing without a real camera

A built-in, stateful mock ONVIF device — Set persists, Get reflects it — covering every operation oxvif implements (157 SOAP actions, and a test asserts none is missing). Two lenses, one behind the other.

Try it now — a test that needs nothing

[dev-dependencies]
oxvif = { version = "0.15", features = ["mock"] }

use std::sync::Arc;
use oxvif::{OnvifClient, mock::MockTransport};

#[tokio::test]
async fn my_code_handles_a_camera() {
    let client = OnvifClient::new("http://mock")
        .with_transport(Arc::new(MockTransport::new()));

    // A real Set → Get round-trip. No network, no sockets, no hardware.
    client.set_hostname("lab-cam").await.unwrap();
    assert_eq!(
        client.get_hostname().await.unwrap().name.as_deref(),
        Some("lab-cam"),
    );
}

cargo test — that's it. Nothing to start, nothing to clean up.

Which one do I want?

Start with MockTransport. Reach for MockServer when you want the real transport in the loop, or when something outside your test — OxDM, Frigate, ONVIF Device Manager — needs an ONVIF device to talk to.

use oxvif::{OnvifSession, mock::MockServer};

#[tokio::test]
async fn over_real_http() -> Result<(), oxvif::OnvifError> {
    let server = MockServer::start().await.unwrap();   // ephemeral 127.0.0.1 port

    // An ordinary session — nothing injected, the real HTTP stack runs.
    let session = OnvifSession::builder(server.device_url()).build().await?;
    assert_eq!(session.get_device_info().await?.manufacturer, "oxvif-mock");
    Ok(())
}   // the server shuts down when dropped

Making it misbehave

The point of a mock is the cases a real camera won't reproduce on demand:

let mock = MockTransport::new();

// Seed the device into the state you need:
mock.device().modify(|s| s.hostname = "seeded-cam".into());

// Arm a single-shot fault for the next matching call:
mock.inject_fault("GetProfiles", "ter:NotAuthorized", "denied");

let client = OnvifClient::new("http://mock").with_transport(Arc::new(mock.clone()));
assert!(client.get_profiles("http://mock/media").await.is_err());  // consumes it

// Then assert what your code did to the device:
client.set_hostname("after").await.unwrap();
assert_eq!(mock.device().read().hostname, "after");

MockTransport is Clone and every clone shares one device state, so the handle you keep and the one the client holds are the same device. MockServer has the same three methods (.device(), .inject_fault(), .clear_faults()).

Both default to no authentication so tests stay frictionless — call .with_auth() (MockTransport) or .enforce_auth(true) (MockServer::builder()) to exercise WS-Security.

Reference

Everything from here down is detail. The blocks above are enough to use it.

1. MockTransport — embedded in the client (in-process, no sockets, no axum):

use std::sync::Arc;
use oxvif::{OnvifClient, mock::MockTransport};

#[tokio::test]
async fn embedded_mock() {
    let client = OnvifClient::new("http://mock")
        .with_transport(Arc::new(MockTransport::new()));

    client.set_hostname("lab-cam").await.unwrap();
    let h = client.get_hostname().await.unwrap();   // Set → Get round-trips
    assert_eq!(h.name.as_deref(), Some("lab-cam"));
}

Or keep the MockTransport as its own named handle instead of constructing it inline — then you can seed/inspect its state and arm faults directly on it. It's Clone, and every clone shares one device state, so hand a clone to the client:

use std::sync::Arc;
use oxvif::OnvifClient;
use oxvif::mock::MockTransport;

#[tokio::test]
async fn standalone_transport_handle() {
    let mock = MockTransport::new();                 // an independent object

    // Drive the mock directly — no client needed:
    mock.device().modify(|s| s.hostname = "seeded-cam".into());      // seed state
    mock.inject_fault("GetProfiles", "ter:NotAuthorized", "denied"); // arm one error

    // Share it with a client (clone — both sides see the same state):
    let client = OnvifClient::new("http://mock").with_transport(Arc::new(mock.clone()));

    assert_eq!(
        client.get_hostname().await.unwrap().name.as_deref(),
        Some("seeded-cam"),
    );
    assert!(client.get_profiles("http://mock/media").await.is_err()); // consumes the fault

    // Inspect, off the handle, what the client changed:
    client.set_hostname("after").await.unwrap();
    assert_eq!(mock.device().read().hostname, "after");
}

2. MockServer — a standalone server you connect to over real HTTP (needs the mock-server feature). Start it on its own port and point an ordinary OnvifClient / OnvifSession at it — nothing is injected into the client, so the real HTTP transport (and, optionally, WS-Security) is exercised end-to-end:

use oxvif::{OnvifSession, mock::MockServer};

#[tokio::test]
async fn standalone_server() -> Result<(), oxvif::OnvifError> {
    let server = MockServer::start().await.unwrap();   // ephemeral 127.0.0.1 port

    // A normal session talking to the mock over HTTP — no transport swap.
    let session = OnvifSession::builder(server.device_url()).build().await?;
    assert_eq!(session.get_device_info().await?.manufacturer, "oxvif-mock");

    // Arm an error for the next GetProfiles to test your error handling.
    server.inject_fault("GetProfiles", "ter:NotAuthorized", "denied");
    assert!(session.get_profiles().await.is_err());
    Ok(())
}   // server shuts down when dropped

Both default to no authentication (frictionless tests) — call .with_auth() (MockTransport) / .enforce_auth(true) (MockServer::builder()) to exercise WS-Security. State is in-memory; opt into persistence via MockState::set_on_change.

Full reference: docs/mock-server.md. What the mock answers for all 157 operations, which are state-backed and which are static, the complete seeded fixture, worked request/response examples, the fault catalogue, and what it deliberately does not model. Essential reading if you drive it from a non-Rust ONVIF client.

oxvif::mock API reference

MockTransport (mock feature) — in-process Transport; Clone + Default; pass via OnvifClient::with_transport(Arc::new(..)):

MockServer (mock-server feature) — bound-port HTTP server; shuts down on drop: