Crate oxide_sdk

Expand description

§Oxide SDK

Guest-side SDK for building WebAssembly applications that run inside the Oxide browser. This crate provides safe Rust wrappers around the raw host-imported functions exposed by the "oxide" wasm import module.

§Quick Start

Add oxide-sdk to your Cargo.toml and set crate-type = ["cdylib"]:

[lib]
crate-type = ["cdylib"]

[dependencies]
oxide-sdk = "0.2"

Then write your app:

use oxide_sdk::*;

#[no_mangle]
pub extern "C" fn start_app() {
    log("Hello from Oxide!");
    canvas_clear(30, 30, 46, 255);
    canvas_text(20.0, 40.0, 28.0, 255, 255, 255, "Welcome to Oxide");
}

Build with cargo build --target wasm32-unknown-unknown --release.

§Interactive Apps

For apps that need a render loop, export on_frame:

use oxide_sdk::*;

#[no_mangle]
pub extern "C" fn start_app() {
    log("Interactive app started");
}

#[no_mangle]
pub extern "C" fn on_frame(_dt_ms: u32) {
    canvas_clear(30, 30, 46, 255);
    let (mx, my) = mouse_position();
    canvas_circle(mx, my, 20.0, 255, 100, 100, 255);

    if ui_button(1, 20.0, 20.0, 100.0, 30.0, "Click me!") {
        log("Button was clicked!");
    }
}

§API Categories

Category	Functions
Canvas	`canvas_clear`, `canvas_rect`, `canvas_circle`, `canvas_text`, `canvas_line`, `canvas_image`, `canvas_dimensions`
Console	`log`, `warn`, `error`
HTTP	`fetch`, `fetch_get`, `fetch_post`, `fetch_post_proto`, `fetch_put`, `fetch_delete`
Protobuf	`proto::ProtoEncoder`, `proto::ProtoDecoder`
Storage	`storage_set`, `storage_get`, `storage_remove`, `kv_store_set`, `kv_store_get`, `kv_store_delete`
Audio	`audio_play`, `audio_play_url`, `audio_detect_format`, `audio_play_with_format`, `audio_last_url_content_type`, `audio_pause`, `audio_channel_play`
Video	`video_load`, `video_load_url`, `video_render`, `video_play`, `video_hls_open_variant`, `subtitle_load_srt`
Media capture	`camera_open`, `camera_capture_frame`, `microphone_open`, `microphone_read_samples`, `screen_capture`, `media_pipeline_stats`
Timers	`set_timeout`, `set_interval`, `clear_timer`, `time_now_ms`
Navigation	`navigate`, `push_state`, `replace_state`, `get_url`, `history_back`, `history_forward`
Input	`mouse_position`, `mouse_button_down`, `key_down`, `key_pressed`, `scroll_delta`
Widgets	`ui_button`, `ui_checkbox`, `ui_slider`, `ui_text_input`
Crypto	`hash_sha256`, `hash_sha256_hex`, `base64_encode`, `base64_decode`
Other	`clipboard_write`, `clipboard_read`, `random_u64`, `random_f64`, `notify`, `upload_file`, `load_module`

§Full API Documentation

See https://docs.oxide.foundation/oxide_sdk/ for the complete API reference, or browse the individual function documentation below.

Modules§

proto: Lightweight protobuf wire-format encoder/decoder.

Structs§

FetchResponse: Response from an HTTP fetch call.
UploadedFile: File returned from the native file picker.

Enums§

AudioFormat: Detected or hinted audio container (host codes: 0 unknown, 1 WAV, 2 MP3, 3 Ogg, 4 FLAC).
VideoFormat: Container or hint for video_load_with_format (host codes: 0 unknown, 1 MP4, 2 WebM, 3 AV1).

Constants§

Functions§

alt_held: Returns true if Alt is held.
audio_channel_play: Play audio on a specific channel. Multiple channels play simultaneously. Channel 0 is the default used by audio_play. Use channels 1+ for layered sound effects, background music, etc.
audio_channel_play_with_format: Like audio_channel_play with an optional AudioFormat hint.
audio_channel_set_volume: Set volume for a specific channel (0.0 silent, 1.0 normal, up to 2.0 boost).
audio_channel_stop: Stop playback on a specific channel.
audio_detect_format: Sniff the container/codec from raw bytes (magic bytes / MP3 sync). Does not decode audio.
audio_duration: Get the total duration of the currently loaded track in milliseconds. Returns 0 if unknown or nothing is loaded.
audio_get_volume: Get the current audio volume.
audio_is_playing: Returns true if audio is currently playing (not paused and not empty).
audio_last_url_content_type: Content-Type header from the last successful audio_play_url response (may be empty).
audio_pause: Pause audio playback.
audio_play: Play audio from encoded bytes (WAV, MP3, OGG, FLAC). The host decodes and plays the audio. Returns 0 on success, negative on error.
audio_play_url: Fetch audio from a URL and play it. The host sends an Accept header listing supported codecs, records the response Content-Type, and rejects obvious HTML/JSON error bodies when no audio signature is found (-4). Returns 0 on success, negative on error.
audio_play_with_format: Play with an optional format hint (AudioFormat::Unknown = same as audio_play). If the hint disagrees with what the host sniffs from the bytes, the host logs a warning but still decodes.
audio_position: Get the current playback position in milliseconds.
audio_resume: Resume paused audio playback.
audio_seek: Seek to a position in milliseconds. Returns 0 on success, negative on error.
audio_set_loop: Enable or disable looping on the default channel. When enabled, subsequent audio_play calls will loop indefinitely.
audio_set_volume: Set audio volume. 1.0 is normal, 0.0 is silent, up to 2.0 for boost.
audio_stop: Stop audio playback and clear the queue.
base64_decode: Decode a base64-encoded string back to bytes.
base64_encode: Base64-encode arbitrary bytes.
camera_capture_frame: Captures one RGBA8 frame into out. Returns the number of bytes written (0 if the camera is not open or capture failed). Query camera_frame_dimensions after a successful write.
camera_close: Stops the camera stream opened by camera_open.
camera_frame_dimensions: Width and height in pixels of the last camera_capture_frame buffer.
camera_open: Opens the default camera after a host permission dialog.
canvas_circle: Draw a filled circle.
canvas_clear: Clear the canvas with a solid RGBA color.
canvas_dimensions: Returns (width, height) of the canvas in pixels.
canvas_image: Draw an image on the canvas from encoded image bytes (PNG, JPEG, GIF, WebP). The browser decodes the image and renders it at the given rectangle.
canvas_line: Draw a line between two points.
canvas_rect: Draw a filled rectangle.
canvas_text: Draw text on the canvas.
clear_hyperlinks: Remove all previously registered hyperlinks.
clear_timer: Cancel a timer previously created with set_timeout or set_interval.
clipboard_read: Read text from the system clipboard.
clipboard_write: Copy text to the system clipboard.
ctrl_held: Returns true if Ctrl (or Cmd on macOS) is held.
error: Print an error to the browser console.
fetch: Perform an HTTP request. Returns the status code and response body.
fetch_delete: HTTP DELETE.
fetch_get: HTTP GET request.
fetch_post: HTTP POST with raw bytes.
fetch_post_proto: HTTP POST with protobuf body (sets Content-Type: application/protobuf).
fetch_put: HTTP PUT with raw bytes.
get_location: Get the device’s mock geolocation as a "lat,lon" string.
get_state: Retrieve the opaque state bytes attached to the current history entry. Returns None if no state has been set.
get_url: Get the URL of the currently loaded page.
hash_sha256: Compute the SHA-256 hash of the given data. Returns 32 bytes.
hash_sha256_hex: Return SHA-256 hash as a lowercase hex string.
history_back: Navigate backward in history. Returns true if a navigation was queued.
history_forward: Navigate forward in history. Returns true if a navigation was queued.
history_length: Return the total number of entries in the history stack.
key_down: Returns true if the given key is currently held down. See KEY_* constants for key codes.
key_pressed: Returns true if the given key was pressed this frame.
kv_store_delete: Delete a key from the persistent KV store. Returns true on success.
kv_store_get: Retrieve a value from the persistent KV store. Returns None if the key does not exist.
kv_store_get_str: Convenience wrapper: retrieve a UTF-8 string value.
kv_store_set: Store a key-value pair in the persistent on-disk KV store. Returns true on success.
kv_store_set_str: Convenience wrapper: store a UTF-8 string value.
load_module: Fetch and execute another .wasm module from a URL. The loaded module shares the same canvas, console, and storage context. Returns 0 on success, negative error code on failure.
log: Print a message to the browser console (log level).
media_pipeline_stats: Host-side pipeline counters: total camera frames captured (high 32 bits) and current microphone ring depth in samples (low 32 bits).
microphone_close
microphone_open: Starts microphone capture (mono f32 ring buffer) after a host permission dialog.
microphone_read_samples: Dequeues up to out.len() mono f32 samples from the microphone ring buffer. Returns how many samples were written.
microphone_sample_rate: Sample rate of the opened input stream in Hz (0 if the microphone is not open).
modifiers: Returns modifier key state as a bitmask: bit 0 = Shift, bit 1 = Ctrl, bit 2 = Alt.
mouse_button_clicked: Returns true if the given mouse button was clicked this frame.
mouse_button_down: Returns true if the given mouse button is currently held down. Button 0 = primary (left), 1 = secondary (right), 2 = middle.
mouse_position: Get the mouse position in canvas-local coordinates.
navigate: Navigate to a new URL. The URL can be absolute or relative to the current page. Navigation happens asynchronously after the current start_app returns. Returns 0 on success, negative on invalid URL.
notify: Send a notification to the user (rendered in the browser console).
push_state: Push a new entry onto the browser’s history stack without triggering a module reload. This is analogous to history.pushState() in web browsers.
random_f64: Get a random f64 in [0, 1).
random_u64: Get a random u64 from the host.
register_hyperlink: Register a rectangular region on the canvas as a clickable hyperlink.
replace_state: Replace the current history entry (no new entry is pushed). Analogous to history.replaceState().
screen_capture: Captures the primary display as RGBA8 after permission dialogs (OS may prompt separately).
screen_capture_dimensions: Width and height of the last screen_capture image.
scroll_delta: Get the scroll wheel delta for this frame.
set_interval: Schedule a repeating timer that fires every interval_ms milliseconds. When it fires the host calls your exported on_timer(callback_id). Returns a timer ID that can be passed to clear_timer.
set_timeout: Schedule a one-shot timer that fires after delay_ms milliseconds. When it fires the host calls your exported on_timer(callback_id). Returns a timer ID that can be passed to clear_timer.
shift_held: Returns true if Shift is held.
storage_get: Retrieve a value from local storage. Returns empty string if not found.
storage_remove: Remove a key from local storage.
storage_set: Store a key-value pair in sandboxed local storage.
subtitle_clear
subtitle_load_srt: Load SubRip subtitles (cues rendered on video_render).
subtitle_load_vtt: Load WebVTT subtitles.
time_now_ms: Get the current time in milliseconds since the UNIX epoch.
ui_button: Render a button at the given position. Returns true if it was clicked on the previous frame.
ui_checkbox: Render a checkbox. Returns the current checked state.
ui_slider: Render a slider. Returns the current value.
ui_text_input: Render a single-line text input. Returns the current text content.
upload_file: Opens the native OS file picker and returns the selected file. Returns None if the user cancels.
url_decode: Decode a percent-encoded string.
url_encode: Percent-encode a string for safe inclusion in URL components.
url_resolve: Resolve a relative URL against a base URL (WHATWG algorithm). Returns None if either URL is invalid.
video_detect_format: Sniff container from leading bytes (magic only; does not decode).
video_duration
video_get_volume
video_hls_open_variant: Open a variant playlist by index (after loading a master with video_load_url).
video_hls_variant_count: Number of variant stream URIs parsed from the last HLS master playlist (0 if not a master).
video_hls_variant_url: Resolved variant URL for index, written into buf-style API (use fixed buffer).
video_last_url_content_type: Content-Type from the last successful video_load_url (may be empty).
video_load: Load video from encoded bytes (MP4, WebM, etc.). Requires FFmpeg on the host. Returns 0 on success, negative on error.
video_load_url: Open a progressive or adaptive (HLS) URL. The host uses FFmpeg; master playlists may list variants.
video_load_with_format: Load with a VideoFormat hint (unknown = same as video_load).
video_pause
video_play
video_position
video_render: Draw the current video frame into the given rectangle (same coordinate space as canvas).
video_seek
video_set_loop
video_set_pip: Floating picture-in-picture preview (host mirrors the last rendered frame).
video_set_volume: Volume multiplier for the video track (0.0–2.0; embedded audio mixing may follow in future hosts).
video_stop
warn: Print a warning to the browser console.

Crate oxide_sdk

Crate oxide_sdk Copy item path

§Oxide SDK

§Quick Start

§Interactive Apps

§API Categories

§Full API Documentation

Modules§

Structs§

Enums§

Constants§

Functions§

Crate oxide_sdk