### Start Disc Playback with Menus

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Initiates playback from the 'First Play' title, utilizing on-disc menus. Requires event handling setup using bd_read_ext().

```c
int bd_play(BLURAY *bd);
```

--------------------------------

### Main Function for Disc Opening and Reading

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

This is the main entry point for the debugging example. It handles command-line arguments to get the disc path, opens the Blu-ray disc using `bd_open`, calls `dump_disc_structure`, attempts to read the INDEX.BDM file using `bd_read_file`, and finally closes the disc with `bd_close`.

```c
int main(int argc, char *argv[]) {
    if (argc < 2) {
        printf("Usage: %s <disc_path>\n", argv[0]);
        return 1;
    }
    
    BLURAY *bd = bd_open(argv[1], NULL);
    if (!bd) {
        printf("Failed to open disc\n");
        return 1;
    }
    
    dump_disc_structure(bd);
    
    // Dump some files
    void *data;
    int64_t size;
    if (bd_read_file(bd, "/BDMV/INDEX.BDM", &data, &size)) {
        printf("\nRead INDEX.BDM: %"PRId64" bytes\n", size);
        free(data);
    }
    
    bd_close(bd);
    return 0;
}

```

--------------------------------

### Simulate Key Events (C)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Examples showing how to pass simple key events or press/release events to the BD-J system.

```c
// Simple key event
bd_user_input(bd, -1, BD_VK_DOWN);

// Or with press/release events
bd_user_input(bd, -1, BD_VK_DOWN | BD_VK_KEY_PRESSED);
bd_user_input(bd, -1, BD_VK_DOWN | BD_VK_KEY_RELEASED);
```

--------------------------------

### Start BD-J Playback

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

Manually starts BD-J playback from a specific object. This is useful for direct testing of BD-J applications. Requires a BLURAY object and a 5-character BDJO object name. Returns 1 on success, 0 on error.

```c
int bd_start_bdj(BLURAY *bd, const char* start_object);
```

```c
if (bd_start_bdj(bd, "00001") == 1) {
    printf("BD-J started\n");
} else {
    printf("Failed to start BD-J\n");
}
```

--------------------------------

### Example: Accessing Clip Information

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

Demonstrates iterating through clips of a title and retrieving their CLPI data. Remember to free the CLPI object after use.

```c
BLURAY_TITLE_INFO *title = bd_get_title_info(bd, 0, 0);
if (title) {
    for (unsigned i = 0; i < title->clip_count; i++) {
        struct clpi_cl *clpi = bd_get_clpi(bd, i);
        if (clpi) {
            printf("Clip %u: streams=%u\n", i, /* access clpi fields */);
            bd_free_clpi(clpi);
        }
    }
    bd_free_title_info(title);
}
```

--------------------------------

### Registering ARGB Overlay Procedure with Buffer Allocation

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

Example demonstrating how to allocate an ARGB buffer, set its dimensions and optional synchronization callbacks, and register it with libbluray for overlay processing.

```c
BD_ARGB_BUFFER buffer = {0};
buffer.width = 1920;
buffer.height = 1080;
buffer.buf[0] = malloc(1920 * 1080 * 4);  // PG plane
buffer.buf[1] = malloc(1920 * 1080 * 4);  // IG plane

// Optional: synchronization callbacks
void my_lock(BD_ARGB_BUFFER *b) {
    // Acquire GPU lock, prepare for writing
}

void my_unlock(BD_ARGB_BUFFER *b) {
    // Release GPU lock, trigger rendering
}

buffer.lock = my_lock;
buffer.unlock = my_unlock;

bd_register_argb_overlay_proc(bd, NULL, callback, &buffer);
```

--------------------------------

### Control Playback Rate with Constants (C)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Examples demonstrating how to use constants for common playback rates like paused, normal, and double speed.

```c
// Pause playback
bd_set_rate(bd, BLURAY_RATE_PAUSED);

// Resume normal speed
bd_set_rate(bd, BLURAY_RATE_NORMAL);

// 2x speed
bd_set_rate(bd, 180000);
```

--------------------------------

### bd_start_bdj

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

Manually starts BD-J playback from a specific BD-J object. This is useful for direct testing of BD-J applications.

```APIDOC
## bd_start_bdj

### Description
Start BD-J playback from a specific object.

### Signature
```c
int bd_start_bdj(BLURAY *bd, const char* start_object);
```

### Parameters
#### Path Parameters
- **bd** (BLURAY*) - Required - BLURAY object
- **start_object** (const char*) - Required - 5-character BDJO object name (e.g., "00001")

### Returns
1 on success, 0 on error.

### Details
Manually starts BD-J from the specified object. Normally BD-J is started automatically through the menu system, but this function allows direct testing of BD-J applications.

**Note:** Testing/debugging function.

### Example
```c
if (bd_start_bdj(bd, "00001") == 1) {
    printf("BD-J started\n");
} else {
    printf("Failed to start BD-J\n");
}
```
```

--------------------------------

### Example: ARGB Overlay with Application Buffer

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

Demonstrates registering an ARGB overlay callback when providing an application-allocated frame buffer. Libbluray handles DRAW events, simplifying application logic to manage INIT, FLUSH, and CLOSE events.

```c
// Allocate frame buffer for overlays
BD_ARGB_BUFFER argb_buffer = {0};
argb_buffer.width = 1920;
argb_buffer.height = 1080;
argb_buffer.buf[0] = malloc(1920 * 1080 * 4);  // PG plane
argb_buffer.buf[1] = malloc(1920 * 1080 * 4);  // IG plane

// Optional: implement lock/unlock for synchronization
argb_buffer.lock = my_lock_function;
argb_buffer.unlock = my_unlock_function;

void argb_overlay_callback(void *handle, const struct bd_argb_overlay_s * const ov) {
    if (!ov) return;
    
    switch (ov->cmd) {
        case BD_ARGB_OVERLAY_INIT:
            // Plane initialized, buffer ready
            printf("Overlay initialized: %ux%u\n", ov->w, ov->h);
            break;
        case BD_ARGB_OVERLAY_FLUSH:
            // Rendering complete at pts, update display
            break;
        case BD_ARGB_OVERLAY_CLOSE:
            // Plane closed
            break;
        case BD_ARGB_OVERLAY_DRAW:
            // With application buffer, libbluray handles drawing
            // This event may still be sent for optimization hints
            break;
    }
}

bd_register_argb_overlay_proc(bd, NULL, argb_overlay_callback, &argb_buffer);
```

--------------------------------

### Example: ARGB Overlay without Application Buffer

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

Demonstrates registering an ARGB overlay callback without providing an application buffer. The application is responsible for rendering ARGB pixel data received in DRAW events and handling all other event types.

```c
void argb_overlay_callback(void *handle, const struct bd_argb_overlay_s * const ov) {
    if (!ov) return;
    
    switch (ov->cmd) {
        case BD_ARGB_OVERLAY_INIT:
            printf("Overlay init: %ux%u\n", ov->w, ov->h);
            break;
        case BD_ARGB_OVERLAY_DRAW:
            // Render ov->argb image data
            // ov->stride = stride in pixels
            // ov->h lines, each ov->stride pixels wide
            // Color format: ARGB32 (32-bit per pixel)
            for (int y = 0; y < ov->h; y++) {
                const uint32_t *row = ov->argb + y * ov->stride;
                // Draw row to display
            }
            break;
        case BD_ARGB_OVERLAY_FLUSH:
            // Composite all planes and update display
            break;
        case BD_ARGB_OVERLAY_CLOSE:
            // Hide plane
            break;
    }
}

bd_register_argb_overlay_proc(bd, NULL, argb_overlay_callback, NULL);
```

--------------------------------

### Complete libbluray Error Handling Example

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/errors.md

This C code snippet demonstrates a full error handling workflow for libbluray operations. It covers opening the disc, checking disc information, handling AACS and BD+ protections, selecting a title, and reading data, with specific checks for various error conditions.

```c
#include "bluray.h"
#include <stdio.h>

int main(int argc, char *argv[]) {
    if (argc < 2) {
        fprintf(stderr, "Usage: %s <disc_path>\n", argv[0]);
        return 1;
    }

    // Open disc
    BLURAY *bd = bd_open(argv[1], "/path/to/KEYDB.cfg");
    if (!bd) {
        fprintf(stderr, "Failed to open disc\n");
        return 1;
    }

    // Check disc info
    const BLURAY_DISC_INFO *disc_info = bd_get_disc_info(bd);
    if (!disc_info->bluray_detected) {
        fprintf(stderr, "Not a Blu-Ray disc\n");
        bd_close(bd);
        return 1;
    }

    // Check AACS/BD+ protection
    if (disc_info->aacs_detected) {
        if (!disc_info->aacs_handled) {
            fprintf(stderr, "AACS Error Code: %d\n", disc_info->aacs_error_code);
            switch (disc_info->aacs_error_code) {
                case BD_AACS_NO_PK:
                    fprintf(stderr, "AACS keys not available\n");
                    break;
                case BD_AACS_NO_CONFIG:
                    fprintf(stderr, "AACS configuration missing\n");
                    break;
                case BD_AACS_CORRUPTED_DISC:
                    fprintf(stderr, "Disc AACS structure is corrupted\n");
                    break;
                default:
                    fprintf(stderr, "AACS error: %d\n", disc_info->aacs_error_code);
            }
            bd_close(bd);
            return 1;
        }
        printf("AACS content can be decrypted\n");
    }

    if (disc_info->bdplus_detected) {
        if (!disc_info->bdplus_handled) {
            fprintf(stderr, "BD+ encryption not supported\n");
            bd_close(bd);
            return 1;
        }
        printf("BD+ content can be decrypted\n");
    }

    // Get title count
    uint32_t num_titles = bd_get_titles(bd, TITLES_RELEVANT, 0);
    printf("Found %u titles\n", num_titles);

    // Select and play first title
    if (bd_select_title(bd, 0) == 0) {
        fprintf(stderr, "Failed to select title 0\n");
        bd_close(bd);
        return 1;
    }

    // Read and process data
    unsigned char buf[6144];
    while (1) {
        int bytes = bd_read(bd, buf, 6144);
        if (bytes < 0) {
            fprintf(stderr, "Read error\n");
            break;
        } else if (bytes == 0) {
            printf("End of title\n");
            break;
        }
        // Process MPEG-TS data
    }

    bd_close(bd);
    return 0;
}

```

--------------------------------

### Get Sound Effect Data

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Fetches sound effect data for menu navigation sounds. This function returns audio sample data in LPCM format.

```c
int bd_get_sound_effect(BLURAY *bd, unsigned sound_id, struct bd_sound_effect *effect);
```

--------------------------------

### Seek to Playmark

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Seeks to a specified playmark. Playmarks are indexed starting from 0.

```c
int64_t bd_seek_mark(BLURAY *bd, unsigned mark);
```

--------------------------------

### bd_play

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Starts playback from the 'First Play' title, utilizing on-disc menus. This function requires event handling via bd_read_ext() for proper menu interaction. Stream selection is managed by the disc menus.

```APIDOC
## bd_play

### Description
Starts disc playback with on-disc menus.

### Signature
```c
int bd_play(BLURAY *bd)
```

### Parameters
#### Path Parameters
- **bd** (BLURAY*) - Required - BLURAY object

### Returns
- 1 on success
- 0 on error
```

--------------------------------

### Play Specific Title with Menus

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Starts playback of a designated title on the disc, respecting on-disc menus. The title parameter specifies which title to play.

```c
int bd_play_title(BLURAY *bd, unsigned title);
```

--------------------------------

### Set Java Runtime Environment Path

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/configuration.md

Specifies the filesystem path to the Java Runtime Environment (JRE) installation. If not set, libbluray attempts to auto-detect the JVM.

```c
bd_set_player_setting_str(bd, BLURAY_PLAYER_JAVA_HOME, "/usr/lib/jvm/default-java");
```

--------------------------------

### Get Number of Titles and Populate List

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Call after bd_open() and before bd_select_title(). Populates the internal title list and applies filtering. Filtering flags allow removal of duplicate titles or clips.

```c
uint32_t bd_get_titles(BLURAY *bd, uint8_t flags, uint32_t min_title_length);
```

```c
uint32_t num_titles = bd_get_titles(bd, TITLES_RELEVANT, 60);
printf("Found %u main titles\n", num_titles);
```

--------------------------------

### libbluray Functions for Interactive Playback

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

This snippet outlines libbluray functions for handling Blu-ray discs with on-disc menus, enabling interactive playback. It includes functions for starting playback, reading data with events, and processing user input.

```c
bd_open(path, keyfile)
bd_play(bd)                    // Start from First Play
bd_read_ext(bd, buf, len, &event)  // Read + get events
// Handle events: selection, stream changes, menu operations
bd_user_input(bd, pts, key)    // Process remote control
```

--------------------------------

### Get Title Information and Navigate Chapters/Angles

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

Retrieves detailed information about a specific title, including chapter and angle counts. Allows seeking to specific chapters and selecting different angles.

```c
BLURAY_TITLE_INFO *title = bd_get_title_info(bd, 0, 0);
printf("Title has %u chapters and %u angles\n", 
       title->chapter_count, title->angle_count);

// Jump to chapter 5
bd_seek_chapter(bd, 5);

// Switch to angle 2
bd_select_angle(bd, 2);

// Read updated data
unsigned char buf[6144];
bd_read(bd, buf, 6144);

bd_free_title_info(title);
```

--------------------------------

### Get Next Event from libbluray Queue

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Use to retrieve events from the libbluray event queue. Pass NULL to initialize, then repeatedly call with a non-NULL pointer to dequeue events. Events cover playback state, stream selections, menus, and errors.

```c
int bd_get_event(BLURAY *bd, BD_EVENT *event);
```

```c
BD_EVENT event;
bd_get_event(bd, NULL);  // Initialize
while (bd_get_event(bd, &event)) {
    printf("Event: %s, param: %u\n", bd_event_name(event.event), event.param);
}
```

--------------------------------

### bd_tell_time

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Gets the current playback time in 90kHz ticks.

```APIDOC
## bd_tell_time

### Description
Get current playback time.

### Signature
```c
uint64_t bd_tell_time(BLURAY *bd);
```

### Parameters
#### Path Parameters
- **bd** (BLURAY*) - Required - BLURAY object

### Returns
Current time in 90kHz ticks.
```

--------------------------------

### Compile libbluray with Meson and Ninja

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

Use these commands to set up the build environment and compile libbluray. Specify '--default-library=static' for static linking.

```bash
mkdir build && cd build
meson setup .. --default-library=static  # for static linking
ninja
```

--------------------------------

### bd_tell

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Gets the current byte position within the title.

```APIDOC
## bd_tell

### Description
Get current byte position in the title.

### Signature
```c
uint64_t bd_tell(BLURAY *bd);
```

### Parameters
#### Path Parameters
- **bd** (BLURAY*) - Required - BLURAY object

### Returns
Current seek position in bytes.
```

--------------------------------

### bd_get_title_size

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Gets the file size of the currently selected title.

```APIDOC
## bd_get_title_size

### Description
Get the file size of the currently selected title.

### Signature
```c
uint64_t bd_get_title_size(BLURAY *bd);
```

### Parameters
#### Path Parameters
- **bd** (BLURAY*) - Required - BLURAY object

### Returns
File size in bytes, 0 if no title selected.
```

--------------------------------

### Initialize BLURAY Object

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Use `bd_init` to create a BLURAY object before opening a disc. This object must be closed with `bd_close`.

```c
BLURAY *bd_init(void);
```

```c
BLURAY *bd = bd_init();
if (bd) {
    bd_open_disc(bd, "/mnt/bluray", "/path/to/KEYDB.cfg");
    // ... use bd
    bd_close(bd);
}
```

--------------------------------

### Get the Currently Selected Title Index

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Retrieves the index of the title that is currently selected for playback.

```c
uint32_t bd_get_current_title(BLURAY *bd);
```

--------------------------------

### Open Blu-Ray Disc (Shortcut)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Use `bd_open` as a convenient way to initialize and open a Blu-ray disc in a single call. It's a shortcut for `bd_open_disc(bd_init(), device_path, keyfile_path)`.

```c
BLURAY *bd_open(const char *device_path, const char *keyfile_path);
```

```c
BLURAY *bd = bd_open("/mnt/bluray", NULL);
if (!bd) {
    fprintf(stderr, "Failed to open disc\n");
    return;
}
// Use disc
bd_close(bd);
```

--------------------------------

### Get Human-Readable Event Name

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Converts a numerical event type into a human-readable string. Useful for logging or debugging event information.

```c
const char *bd_event_name(uint32_t event);
```

--------------------------------

### Register Overlay Callbacks for Menu Rendering

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

Sets up callback functions for handling YUV and ARGB overlays, which are crucial for rendering menus and subtitles.

```c
// Register overlay callbacks for menu rendering
bd_register_overlay_proc(bd, handle, yuv_overlay_callback);
bd_register_argb_overlay_proc(bd, handle, argb_overlay_callback, NULL);
```

--------------------------------

### Encode Display Size in Centimeters

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/configuration.md

Use this macro to encode the display size in centimeters for configuration. For example, to set a 55cm display size.

```c
BLURAY_DCAP_DISPLAY_SIZE(cm)  // Encodes display size in centimeters
// Example: BLURAY_DCAP_DISPLAY_SIZE(55) for a 55cm display
```

--------------------------------

### Get Playlist Information

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Retrieves detailed information for a specific playlist, essential for menu-based navigation. The returned structure must be freed using `bd_free_title_info()`.

```c
BLURAY_TITLE_INFO* bd_get_playlist_info(BLURAY *bd, uint32_t playlist, unsigned angle);
```

--------------------------------

### Open Directory for Enumeration in Blu-ray VFS

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

Opens a directory from the Blu-Ray Virtual File System for listing its contents. Use the directory's `next()` method to iterate entries and `close()` to release it.

```c
struct bd_dir_s *bd_open_dir(BLURAY *bd, const char *dir);
```

```c
struct bd_dir_s *dir = bd_open_dir(bd, "/BDMV/PLAYLIST");
if (dir) {
    // Iterate directory entries using dir->next()
    dir->close(dir);
}
```

--------------------------------

### Playback Loop with Event Handling

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

Initiates playback and enters a loop to continuously read extended data, process events (like menu interactions or stream changes), and handle user input.

```c
// Start playback
bd_play(bd);

// Event loop
BD_EVENT event;
bd_get_event(bd, NULL);  // Initialize
while (1) {
    unsigned char buf[6144];
    int len = bd_read_ext(bd, buf, 6144, &event);
    
    if (len < 0) break;  // Error
    if (len == 0 && event.event == BD_EVENT_NONE) {
        // No data and no events - keep reading
    } else if (event.event != BD_EVENT_NONE) {
        // Handle event (menu selection, stream change, etc.)
    }
    
    if (len > 0) {
        // Feed to decoder
    }
    
    // Process user input
    if (user_pressed_down) {
        bd_user_input(bd, current_pts, BD_VK_DOWN);
    }
    if (user_pressed_enter) {
        bd_user_input(bd, current_pts, BD_VK_ENTER);
    }
}
```

--------------------------------

### Get Information About a Specific Title

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Returns detailed information including clips, chapters, marks, duration, and angle count. Must be freed with bd_free_title_info().

```c
BLURAY_TITLE_INFO* bd_get_title_info(BLURAY *bd, uint32_t title_idx, unsigned angle);
```

```c
BLURAY_TITLE_INFO *info = bd_get_title_info(bd, 0, 0);
if (info) {
    printf("Duration: %"PRIu64" (90kHz ticks)\n", info->duration);
    printf("Clips: %u\n", info->clip_count);
    printf("Chapters: %u\n", info->chapter_count);
    printf("Angles: %u\n", info->angle_count);
    bd_free_title_info(info);
}
```

--------------------------------

### Initialize and Open Blu-ray Disc

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

Opens a Blu-ray disc from a given path and keyfile. It's essential to check for copy protection (AACS) after opening.

```c
BLURAY *bd = bd_open(path, keyfile);
const BLURAY_DISC_INFO *info = bd_get_disc_info(bd);

// Check for protection
if (info->aacs_detected && !info->aacs_handled) { /* error */ }
```

--------------------------------

### Open Directory from Blu-ray VFS

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Opens a directory for iteration. The opened directory must be closed using its corresponding close method.

```c
struct bd_dir_s *bd_open_dir(BLURAY *bd, const char *dir);
```

--------------------------------

### Dump Directory Contents

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

This function opens a directory on the Blu-ray disc and prints its path. The actual enumeration of entries using `dir->next()` is commented out and depends on the `bd_dir_s` structure implementation. It demonstrates the usage of `bd_open_dir` and `dir->close`.

```c
void dump_files(BLURAY *bd, const char *dir_path, int depth) {
    struct bd_dir_s *dir = bd_open_dir(bd, dir_path);
    if (!dir) {
        printf("Failed to open %s\n", dir_path);
        return;
    }
    
    printf("%s:\n", dir_path);
    // Use dir->next() to enumerate entries
    // (implementation depends on bd_dir_s structure)
    
    dir->close(dir);
}

```

--------------------------------

### Get Disc Metadata

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Retrieves disc metadata, such as disc name and title information, in the currently selected language. Referenced thumbnail images should be read using bd_get_meta_file().

```c
const struct meta_dl *meta = bd_get_meta(bd);
```

--------------------------------

### Configure libbluray Player Settings

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/configuration.md

Use this snippet to set player preferences such as audio/subtitle languages, country code, region code, subtitle decoding, output preference, UHD profile, and BD-J persistent storage. Ensure libbluray is properly initialized before calling these functions.

```c
#include "bluray.h"

int main() {
    BLURAY *bd = bd_open("/mnt/bluray", NULL);
    if (!bd) return 1;

    // Set regional preferences
    bd_set_player_setting_str(bd, BLURAY_PLAYER_SETTING_AUDIO_LANG, "eng");
    bd_set_player_setting_str(bd, BLURAY_PLAYER_SETTING_PG_LANG, "eng");
    bd_set_player_setting_str(bd, BLURAY_PLAYER_SETTING_MENU_LANG, "eng");
    bd_set_player_setting_str(bd, BLURAY_PLAYER_SETTING_COUNTRY_CODE, "US");

    // Set region code
    bd_set_player_setting(bd, BLURAY_PLAYER_SETTING_REGION_CODE, BLURAY_REGION_A);

    // Enable subtitle decoder
    bd_set_player_setting(bd, BLURAY_PLAYER_SETTING_DECODE_PG, 1);

    // Set 2D output preference
    bd_set_player_setting(bd, BLURAY_PLAYER_SETTING_OUTPUT_PREFER, BLURAY_OUTPUT_PREFER_2D);

    // Configure player profile for UHD playback
    bd_set_player_setting(bd, BLURAY_PLAYER_SETTING_PLAYER_PROFILE, BLURAY_PLAYER_PROFILE_6_v3_0);

    // Configure BD-J storage
    bd_set_player_setting_str(bd, BLURAY_PLAYER_PERSISTENT_ROOT, "/home/user/.bluray/persistent");
    bd_set_player_setting(bd, BLURAY_PLAYER_SETTING_PERSISTENT_STORAGE, 1);

    // Use disc
    bd_close(bd);
    return 0;
}
```

--------------------------------

### Get libbluray Runtime Version

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Retrieves the current runtime version of the libbluray library. Pass pointers to integers to store the major, minor, and micro version numbers.

```c
int major, minor, micro;
bd_get_version(&major, &minor, &micro);
printf("LibBluray version: %d.%d.%d\n", major, minor, micro);
```

--------------------------------

### bd_init

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Initializes a BLURAY object without opening a disc. This object can then be used with other bd_open_* functions. It must be closed with bd_close().

```APIDOC
## bd_init

### Description
Initialize a BLURAY object without opening a disc.

### Returns
Allocated BLURAY object on success, NULL on error.

### Details
Creates an empty BLURAY instance that can be passed to `bd_open_disc()`, `bd_open_stream()`, or `bd_open_files()` functions. Must be closed with `bd_close()`.

### Example
```c
BLURAY *bd = bd_init();
if (bd) {
    bd_open_disc(bd, "/mnt/bluray", "/path/to/KEYDB.cfg");
    // ... use bd
    bd_close(bd);
}
```
```

--------------------------------

### Get Clip Information (CLPI)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-debugging.md

Retrieves a parsed CLPI object for a given playitem reference. Use this to access detailed stream and timing information for a specific clip.

```c
struct clpi_cl *bd_get_clpi(BLURAY *bd, unsigned clip_ref);
```

--------------------------------

### bd_open

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Opens a Blu-Ray disc in a single call, initializing a BLURAY object and opening the specified device path.

```APIDOC
## bd_open

### Description
Open a Blu-Ray disc in one call.

### Parameters
#### Path Parameters
- **device_path** (const char*) - Yes - Path to mounted disc, device, or image file
- **keyfile_path** (const char*) - No - Path to KEYDB.cfg file for AACS decryption

### Returns
Allocated BLURAY object on success, NULL on error.

### Details
Shortcut for `bd_open_disc(bd_init(), device_path, keyfile_path)`. This is the most common way to open a disc.

### Example
```c
BLURAY *bd = bd_open("/mnt/bluray", NULL);
if (!bd) {
    fprintf(stderr, "Failed to open disc\n");
    return;
}
// Use disc
bd_close(bd);
```
```

--------------------------------

### Get the Main Title Index

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Returns the index of the main title as determined by disc metadata. Useful for automatically playing the feature film without user menu interaction.

```c
int bd_get_main_title(BLURAY *bd);
```

--------------------------------

### Set Audio and Subtitle Language Preferences

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/README.md

Configures the preferred audio and subtitle languages for playback using string settings.

```c
// Set language preferences
bd_set_player_setting_str(bd, BLURAY_PLAYER_SETTING_AUDIO_LANG, "eng");
bd_set_player_setting_str(bd, BLURAY_PLAYER_SETTING_PG_LANG, "eng");
```

--------------------------------

### Pass User Input (C)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Sends key input to the menu/graphics system. Key codes are defined in `src/libbluray/keys.h`. The application may provide either single key events or press/type/release events.

```c
int bd_user_input(BLURAY *bd, int64_t pts, uint32_t key);
```

--------------------------------

### Handle Missing AACS Configuration Error

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/errors.md

Detect and report BD_AACS_NO_CONFIG errors, which occur when AACS configuration files are missing or inaccessible. Advise users to check libaacs installation and configuration.

```c
if (info->aacs_error_code == BD_AACS_NO_CONFIG) {
    fprintf(stderr, "AACS configuration not found\n");
    fprintf(stderr, "Check libaacs installation and configuration\n");
}
```

--------------------------------

### Open Blu-Ray Disc with Stream I/O

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Implement custom block-level I/O for disc access using `bd_open_stream`. The `read_blocks` callback must return the number of blocks read.

```c
int bd_open_stream(BLURAY *bd,
                   void *read_blocks_handle,
                   int (*read_blocks)(void *handle, void *buf, int lba, int num_blocks));
```

--------------------------------

### Handle bd_set_player_setting / bd_set_player_setting_str Errors

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/errors.md

Check for a return value of 0 to detect failures when setting player properties, such as region codes. Success is indicated by a return value of 1.

```c
if (bd_set_player_setting(bd, BLURAY_PLAYER_SETTING_REGION_CODE, BLURAY_REGION_A) == 0) {
    fprintf(stderr, "Failed to set region code\n");
}
```

--------------------------------

### Define BLURAY_TITLE_MARK Structure

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/types.md

Defines the structure for playmarks (bookmarks/cue points) in a Blu-ray title. Includes mark index, type, start time, duration to the next mark, byte offset, and clip reference.

```c
typedef struct bd_mark {
    uint32_t    idx;       /**< Mark index (number - 1) */
    int         type;      /**< Mark type (bd_mark_type_e) */
    uint64_t    start;     /**< Mark media time, 90kHz, ("playlist time") */
    uint64_t    duration;  /**< Time to next mark in 90kHz ticks */
    uint64_t    offset;    /**< Mark distance from title start, bytes */
    unsigned    clip_ref;  /**< Clip reference (index to playlist clips list) */
} BLURAY_TITLE_MARK;
```

--------------------------------

### YUV Overlay Callback Implementation

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

This C code implements a callback function for handling libbluray overlay events. It initializes, draws, clears, wipes, flushes, and closes overlay planes. Use this when you need to integrate custom overlay rendering with libbluray playback.

```c
#include "bluray.h"
#include "decoders/overlay.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

typedef struct {
    uint32_t *pixels;
    int width;
    int height;
} my_overlay_t;

my_overlay_t my_overlays[2] = {0};  // PG and IG planes

void draw_yuv_rle(my_overlay_t *ov, const BD_OVERLAY *bd_ov) {
    const BD_PG_RLE_ELEM *rle = bd_ov->img;
    const BD_PG_PALETTE_ENTRY *pal = bd_ov->palette;
    
    uint32_t *dst = ov->pixels + bd_ov->y * ov->width + bd_ov->x;
    int y = 0;
    
    while (y < bd_ov->h) {
        uint32_t *line = dst + y * ov->width;
        int x = 0;
        
        while (x < bd_ov->w && rle) {
            uint8_t pal_idx = rle->color;
            BD_PG_PALETTE_ENTRY color = pal[pal_idx];
            uint32_t argb = (color.T << 24) | (color.Cr << 16) |
                            (color.Cb << 8) | color.Y;
            
            for (uint16_t i = 0; i < rle->len && x < bd_ov->w; i++) {
                line[x++] = argb;
            }
            rle++;
        }
        y++;
    }
}

void yuv_overlay_callback(void *handle, const BD_OVERLAY * const bd_ov) {
    if (!bd_ov) return; 
    
    my_overlay_t *ov = &my_overlays[bd_ov->plane];
    
    switch (bd_ov->cmd) {
        case BD_OVERLAY_INIT:
            printf("YUV Overlay INIT: %ux%u at (%u, %u)\n",
                   bd_ov->w, bd_ov->h, bd_ov->x, bd_ov->y);
            if (!ov->pixels) {
                ov->width = 1920;
                ov->height = 1080;
                ov->pixels = calloc(ov->width * ov->height, 4);
            }
            break;
            
        case BD_OVERLAY_DRAW:
            if (bd_ov->img && bd_ov->palette) {
                draw_yuv_rle(ov, bd_ov);
            }
            break;
            
        case BD_OVERLAY_CLEAR:
            memset(ov->pixels, 0, ov->width * ov->height * 4);
            break;
            
        case BD_OVERLAY_WIPE:
            // Clear rectangular area
            for (int y = bd_ov->y; y < bd_ov->y + bd_ov->h; y++) {
                memset(ov->pixels + y * ov->width + bd_ov->x, 0, bd_ov->w * 4);
            }
            break;
            
        case BD_OVERLAY_FLUSH:
            printf("YUV Overlay FLUSH at pts=%
```

```c
PRId64"\n", bd_ov->pts);
            // Update display with ov->pixels
            break;
            
        case BD_OVERLAY_CLOSE:
            if (ov->pixels) {
                free(ov->pixels);
                ov->pixels = NULL;
            }
            break;
    }
}

int main() {
    BLURAY *bd = bd_open("/mnt/bluray", NULL);
    if (!bd) return 1;
    
    bd_register_overlay_proc(bd, NULL, yuv_overlay_callback);
    
    // ... playback code ...
    
    bd_close(bd);
    return 0;
}

```

--------------------------------

### Handle AACS Key Derivation Failure

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/errors.md

Handle BD_AACS_NO_PK errors, indicating failure to derive AACS decryption keys. This often means libaacs is not installed or KEYDB.cfg is missing. Provide guidance on resolving this.

```c
if (info->aacs_error_code == BD_AACS_NO_PK) {
    // AACS key derivation failed
    // Typically means libaacs is not installed or KEYDB.cfg is missing
    fprintf(stderr, "Cannot decrypt AACS content\n");
    fprintf(stderr, "Install libaacs and ensure KEYDB.cfg is configured\n");
}
```

--------------------------------

### bd_argb_overlay_cmd_e Enumeration

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

Enumerates the command types for ARGB overlay events, such as initialization, drawing, flushing, and closing overlay planes.

```c
typedef enum {
    BD_ARGB_OVERLAY_INIT  = 0,    // Initialize overlay plane
    BD_ARGB_OVERLAY_CLOSE = 1,    // Close overlay plane
    BD_ARGB_OVERLAY_DRAW  = 3,    // Draw ARGB image on plane
    BD_ARGB_OVERLAY_FLUSH = 6,    // Flush to display at pts
} bd_argb_overlay_cmd_e;
```

--------------------------------

### Define BLURAY_TITLE_CHAPTER Structure

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/types.md

Defines the structure for chapter entries, used for seeking and display within a Blu-ray title. Contains information about chapter index, start time, duration, byte offset, and clip reference.

```c
typedef struct bd_chapter {
    uint32_t    idx;       /**< Chapter index (number - 1) */
    uint64_t    start;     /**< Start media time, 90kHz, ("playlist time") */
    uint64_t    duration;  /**< Duration in 90kHz ticks */
    uint64_t    offset;    /**< Distance from title start, bytes */
    unsigned    clip_ref;  /**< Clip reference (index to playlist clips list) */
} BLURAY_TITLE_CHAPTER;
```

--------------------------------

### Get Blu-ray Disc Information

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Retrieves a structure containing general disc metadata such as title count, AACS/BD-J detection, and bluray detection status. The returned pointer is valid until the next disc access function is called.

```c
const BLURAY_DISC_INFO *info = bd_get_disc_info(bd);
if (info) {
    printf("Disc detected: %s\n", info->bluray_detected ? "yes" : "no");
    printf("Number of titles: %u\n", info->num_titles);
    printf("AACS detected: %s\n", info->aacs_detected ? "yes" : "no");
    printf("BD-J detected: %s\n", info->bdj_detected ? "yes" : "no");
}
```

--------------------------------

### bd_overlay_cmd_e Enumeration

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

Defines the command types for overlay events, including initialization, drawing, clearing, and flushing.

```APIDOC
## bd_overlay_cmd_e

### Description
Overlay command/event type enumeration.

### Enumerators
- **BD_OVERLAY_INIT** (0) - Initialize overlay plane
- **BD_OVERLAY_CLOSE** (1) - Close overlay plane
- **BD_OVERLAY_CLEAR** (2) - Clear overlay plane
- **BD_OVERLAY_DRAW** (3) - Draw bitmap
- **BD_OVERLAY_WIPE** (4) - Clear area
- **BD_OVERLAY_HIDE** (5) - Overlay is empty and can be hidden
- **BD_OVERLAY_FLUSH** (6) - Flush to display at pts

### Command Processing
| Command | Time | Description |
|---------|------|-------------|
| INIT | Immediate | Initialize plane with size/position |
| CLOSE | Immediate | Close/remove plane |
| CLEAR | Deferred | Clear entire plane (palette/img NULL) |
| DRAW | Deferred | Draw bitmap at x,y,w,h using palette |
| WIPE | Deferred | Clear rectangular area |
| HIDE | Deferred | Plane is empty, can be hidden |
| FLUSH | Synchronization | Apply all deferred changes at pts |

Commands marked "Immediate" execute right away. Commands marked "Deferred" should be queued and applied together when FLUSH is received.

### Source
`src/libbluray/decoders/overlay.h:58`
```

--------------------------------

### Open Blu-Ray Disc with Existing Object

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Use `bd_open_disc` to open a Blu-ray disc using a pre-initialized BLURAY object. Returns 1 on success, 0 on error.

```c
int bd_open_disc(BLURAY *bd, const char *device_path, const char *keyfile_path);
```

```c
BLURAY *bd = bd_init();
if (bd_open_disc(bd, "/mnt/bluray", NULL) == 0) {
    fprintf(stderr, "Failed to open disc\n");
    bd_close(bd);
    return;
}
```

--------------------------------

### YUV Overlay Command Enumeration (C)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/types.md

Specifies the types of YUV overlay events. Commands include initialization, closing, clearing, drawing, wiping, hiding, and flushing overlay planes.

```c
typedef enum {
    BD_OVERLAY_INIT  = 0,    /**< Initialize plane */
    BD_OVERLAY_CLOSE = 1,    /**< Close plane */
    BD_OVERLAY_CLEAR = 2,    /**< Clear plane */
    BD_OVERLAY_DRAW  = 3,    /**< Draw bitmap */
    BD_OVERLAY_WIPE  = 4,    /**< Clear area */
    BD_OVERLAY_HIDE  = 5,    /**< Hide plane */
    BD_OVERLAY_FLUSH = 6,    /**< Flush to display */
} bd_overlay_cmd_e;
```

--------------------------------

### bd_argb_overlay_cmd_e Enumeration

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-overlays.md

Enumeration defining the command types for ARGB overlay events.

```APIDOC
## bd_argb_overlay_cmd_e

### Description
ARGB overlay command enumeration.

### Commands
- **BD_ARGB_OVERLAY_INIT** (0) - Initialize overlay plane - application allocates buffer
- **BD_ARGB_OVERLAY_CLOSE** (1) - Close overlay plane
- **BD_ARGB_OVERLAY_DRAW** (3) - Draw ARGB image on plane
- **BD_ARGB_OVERLAY_FLUSH** (6) - Flush to display at pts
```

--------------------------------

### Read Data with Event Support

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Reads MPEG-TS data from the currently playing title and simultaneously retrieves the next event. Handle the returned event before subsequent calls. Use this instead of bd_read() when menus are active.

```c
int bd_read_ext(BLURAY *bd, unsigned char *buf, int len, BD_EVENT *event);
```

--------------------------------

### Define BLURAY Opaque Type

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/types.md

Represents an open Blu-Ray disc instance. Use bd_init() or bd_open() to create and bd_close() to destroy.

```c
typedef struct bluray BLURAY;
```

--------------------------------

### Select a Title for Playback

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Selects the title for playback. After selection, bd_read() will read from this title. This is for playback without on-disc menus.

```c
int bd_select_title(BLURAY *bd, uint32_t title);
```

```c
if (bd_select_title(bd, 0) == 1) {
    printf("Title 0 selected\n");
}
```

--------------------------------

### ARGB Overlay Event Structure (C)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/types.md

Represents an ARGB overlay event for BD-J menus. Includes timestamp, plane, command, region coordinates, stride, and ARGB image data.

```c
typedef struct bd_argb_overlay_s {
    int64_t  pts;   /**< Event timestamp on video grid */
    uint8_t  plane; /**< Overlay plane (BD_OVERLAY_PG or BD_OVERLAY_IG) */
    uint8_t  cmd;   /**< Event type (bd_argb_overlay_cmd_e) */

    uint16_t x;     /**< Top-left x coordinate */
    uint16_t y;     /**< Top-left y coordinate */
    uint16_t w;     /**< Region width */
    uint16_t h;     /**< Region height */

    uint16_t stride;       /**< ARGB buffer stride in pixels */
    const uint32_t * argb; /**< ARGB image data */
} BD_ARGB_OVERLAY;
```

--------------------------------

### Open Blu-Ray Disc with File I/O

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Use `bd_open_files` to enable custom disc access via directory and file callbacks. This is useful for remote or archived discs.

```c
int bd_open_files(BLURAY *bd,
                  void *handle,
                  struct bd_dir_s *(*open_dir)(void *handle, const char *rel_path),
                  struct bd_file_s *(*open_file)(void *handle, const char *rel_path));
```

--------------------------------

### bd_open_files

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/api-reference-core.md

Opens a Blu-Ray disc using custom file-based I/O, enabling access through directory and file callbacks.

```APIDOC
## bd_open_files

### Description
Open a Blu-Ray disc using custom file-based I/O.

### Parameters
#### Path Parameters
- **bd** (BLURAY*) - Yes - BLURAY object from `bd_init()`
- **handle** (void*) - Yes - Opaque handle passed to callbacks
- **open_dir** (function pointer) - Yes - Callback to open directories
- **open_file** (function pointer) - Yes - Callback to open files

### Returns
1 on success, 0 on error.

### Details
Allows implementation of custom disc access through directory and file callbacks. Useful for remote or archived discs.

### Source
`src/libbluray/bluray.h:404`
```

--------------------------------

### ARGB Overlay Command Enumeration (C)

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/types.md

Defines the types of ARGB overlay events, primarily used for BD-J menus. Supports initialization, closing, drawing, and flushing.

```c
typedef enum {
    BD_ARGB_OVERLAY_INIT  = 0,    /**< Initialize plane */
    BD_ARGB_OVERLAY_CLOSE = 1,    /**< Close plane */
    BD_ARGB_OVERLAY_DRAW  = 3,    /**< Draw ARGB image */
    BD_ARGB_OVERLAY_FLUSH = 6,    /**< Flush to display */
} bd_argb_overlay_cmd_e;
```

--------------------------------

### Handle bd_open_disc / bd_open_files / bd_open_stream Errors

Source: https://github.com/videolan/libbluray/blob/master/_autodocs/errors.md

Check for a return value of 0 to detect failure when opening a disc, files, or stream. Ensure the bluray context is closed if opening fails.

```c
BLURAY *bd = bd_init();
if (bd_open_disc(bd, "/mnt/bluray", NULL) == 0) {
    fprintf(stderr, "Failed to open disc\n");
    bd_close(bd);
    return 1;
}
```