```{csv-table}
**Extension**: {{ extension_version }},**Documentation Generated**: {sub-ref}`today`
```

# Overview

The **omni.client.lib** extension provides foundation APIs for uniformly accessing Nucleus filesystem, local filesystem, HTTP resources, and other storage backends through a single interface. This extension serves as the core client library that handles all file system operations across different protocols and storage systems in the Omniverse ecosystem.

## Concepts

### Unified File System Access
The extension abstracts different storage backends (Nucleus servers, local filesystem, HTTP resources) behind a consistent API. This allows applications to work with files regardless of where they are stored, using the same set of operations for reading, writing, listing, and managing files.

### URL-Based Operations
All file operations use URL-based addressing, supporting various schemes including `omniverse://`, `file://`, and `http://`. The extension provides utilities for URL manipulation, validation, and normalization to ensure consistent handling across different storage types.

### Asynchronous Operations
Most file operations are available in both synchronous and asynchronous variants, with the async versions returning Request objects that can be used to track operation progress or cancel operations before completion.

## Functionality

### File System Operations
**Basic file operations** include reading, writing, copying, moving, and deleting files and folders. These operations work uniformly across all supported storage backends.

**Directory operations** provide listing folder contents, creating directories, and managing folder hierarchies. The [list](omni.client/omni.client.list) function returns detailed metadata including file sizes, modification times, and access permissions.

**Advanced operations** support checkpointing for versioned storage systems, file locking/unlocking, and server-side operations when both source and destination are on the same server.

### URL Utilities
**URL manipulation functions** handle converting between different URL formats, making relative and absolute URLs, and normalizing URLs for consistent comparison. Functions like [make_file_url_if_possible](omni.client/omni.client.make_file_url_if_possible) and [normalize_url](omni.client/omni.client.normalize_url) ensure proper URL formatting across different contexts.

**URL validation** checks if URLs are valid, point to local filesystem, or support advanced features like tagging and omni objects.

### Authentication and Access Control
**Authentication support** includes token-based authentication, device flow authentication, and integration with Nucleus server authentication systems. The [refresh_auth_token](omni.client/omni.client.refresh_auth_token) function manages authentication token lifecycle.

**Access control management** provides getting and setting ACLs (Access Control Lists), managing user groups, and handling permission-based operations through functions like [get_acls](omni.client/omni.client.get_acls) and [set_acls](omni.client/omni.client.set_acls).

### Live Updates and Subscriptions
**Real-time notifications** allow subscribing to file system changes, receiving updates when files are created, modified, or deleted. The `list_subscribe_with_callback` function establishes persistent subscriptions for monitoring folder changes.

**Live collaboration support** includes joining channels for real-time communication and processing live updates from collaborative editing sessions.

## Usage Examples

Here's a basic example of reading a file from different storage backends:

```python
import omni.client

# Read from Nucleus server
result, content = omni.client.read_file("omniverse://server/path/file.usd")
if result == omni.client.Result.OK:
    data = memoryview(content).tobytes()

# Read from local filesystem
result, content = omni.client.read_file("C:/path/to/file.usd")

# Async version for non-blocking operations
def callback(result, version, content):
    if result == omni.client.Result.OK:
        data = memoryview(content).tobytes()

request = omni.client.read_file_async("omniverse://server/file.usd", callback)
```

URL manipulation example:

```python
import omni.client

# Normalize URLs for consistent comparison
url1 = omni.client.normalize_url("omniverse://server/../path/file.usd")
url2 = omni.client.normalize_url("omniverse://server/path/file.usd")

# Check if URLs are equal
if omni.client.equal_urls(url1, url2):
    print("URLs point to the same resource")

# Convert local path to file URL if appropriate
file_url = omni.client.make_file_url_if_possible("C:/absolute/path/file.usd")
```

## Integration

The extension integrates with **omni.kit.async_engine** to provide proper asynchronous operation handling within the Kit framework. This ensures that async file operations don't block the main thread and integrate properly with Kit's event loop system.

For more information, please check [Omniverse Client Library](https://docs.omniverse.nvidia.com/kit/docs/client_library/latest/index.html) documentation.
