### Install live-photo with npm, pnpm, or yarn

Source: https://github.com/iceywu/live-photo/blob/main/README.md

Install the library using your preferred package manager.

```bash
npm install live-photo
# pnpm add live-photo
# yarn add live-photo
```

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

### Example Usage of PreferencesStore Subscription

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Demonstrates how to subscribe to preference changes, update preferences, and unsubscribe. The subscription callback logs changes to the console.

```typescript
const store = createMemoryStore();
const unsubscribe = store.subscribe((prefs) => {
  console.log('Preferences changed:', prefs);
});

store.set({ muted: true });
// Logs: Preferences changed: { muted: true }

unsubscribe(); // Stop listening
store.set({ muted: false });
// No log output
```

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

### Using a New Locale

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/i18n.md

Example of initializing the LivePhotoViewer with a newly added locale, 'es' (Spanish).

```typescript
const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  locale: 'es',
});
```

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

### Initialize and Play LivePhotoViewer

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/LivePhotoViewer.md

Initializes a new LivePhotoViewer instance and starts video playback. Ensure the container element exists and video/photo sources are correctly provided.

```typescript
const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
});

await viewer.play();
```

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

### ElementCustomization Example

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/types.md

An example demonstrating how to use the ElementCustomization interface to apply styles and attributes to an element. This includes setting CSS filters, border-radius, and custom data attributes.

```typescript
const customization: ElementCustomization = {
  styles: {
    filter: 'brightness(1.1)',
    borderRadius: '8px',
  },
  attributes: {
    'data-testid': 'my-element',
    'data-custom': 'value',
  },
};
```

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

### play()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/LivePhotoViewer.md

Starts playback of the video. It resets the video to the start, applies the muted state, triggers haptic feedback if enabled, and hides the photo. If the video is not yet loaded, it will be loaded first. Playback waits until the video is ready.

```APIDOC
## play()

### Description
Starts playback of the video. Resets the video to the start, applies the muted state, triggers haptic feedback if enabled, and hides the photo. Loads the video if not already loaded and waits for it to be ready.

### Method
`async play(): Promise<void>`

### Returns
`Promise<void>` - Resolves when playback begins or immediately if video is already playing.

### Throws
Rejects on playback errors (caught and passed to `onError` callback).

### Behavior
- Loads video if not yet loaded.
- Waits for video to be ready (`canplay` event) before playing.
- Stops immediately if `videoError` state is true.
- Applies optional haptic vibration (200ms) if `enableVibration` is true and `navigator.vibrate` is available.
- Adds `playing` class to container and sets photo opacity to 0.

### Example
```typescript
const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
});

await viewer.play();
```
```

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

### Monitor Live Photo Load Progress

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/errors.md

This example shows how to use onLoadStart, onLoadProgress, and onProgress callbacks to monitor video loading status. It also includes handling for 'VIDEO_LOAD_ERROR' to display loading indicators and error messages.

```typescript
const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  lazyLoadVideo: true,
  onLoadStart: () => {
    console.log('Video download started');
    showLoadingIndicator();
  },
  onLoadProgress: (loaded, total) => {
    const percent = (loaded / total) * 100;
    console.log(`Downloaded: ${percent.toFixed(1)}%`);
    updateProgressBar(percent);
  },
  onProgress: (buffered, event, video) => {
    console.log(`Buffered: ${buffered}%`);
  },
  onError: (error) => {
    if (error.type === 'VIDEO_LOAD_ERROR') {
      hideLoadingIndicator();
      showErrorMessage('Download failed');
    }
  },
});
```

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

### Configure High-Performance Setup

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Optimize for high performance by disabling vibration, using a static badge icon, and setting a specific long press delay. Preloads only metadata.

```typescript
new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  lazyLoadVideo: true,
  enableVibration: false,
  staticBadgeIcon: true,
  longPressDelay: 200,
  preload: 'none',
});
```

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

### Download Extracted Live Photo Components

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/extractFromLivePhoto.md

This example shows how to extract photo and video components from a Live Photo and trigger downloads for each. Ensure to revoke the resources after initiating the downloads.

```typescript
async function downloadLivePhotoComponents(file) {
  const result = await extractFromLivePhoto(file);

  if (!result) {
    console.error('Invalid Live Photo');
    return;
  }

  // Download photo
  const photoLink = document.createElement('a');
  photoLink.href = result.photoUrl;
  photoLink.download = `${file.name.replace(/\.\w+$/, '')}.jpg`;
  photoLink.click();

  // Download video
  const videoLink = document.createElement('a');
  videoLink.href = result.videoUrl;
  videoLink.download = `${file.name.replace(/\.\w+$/, '')}.mp4`;
  videoLink.click();

  // Cleanup
  result.revoke();
}
```

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

### get()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Retrieves a snapshot of the current live photo preferences. This method returns an object containing the current settings without making any changes.

```APIDOC
## get()

### Description
Returns a snapshot of the current preferences.

### Method
GET (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
None

### Response
#### Success Response
- **prefs** (`LivePhotoPrefs`) - Object with `autoplay?: boolean` and `muted?: boolean` fields

### Response Example
```json
{
  "autoplay": true,
  "muted": false
}
```
```

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

### Auto-initialize Live Photo with CDN

Source: https://github.com/iceywu/live-photo/blob/main/README.md

Elements with the `data-live-photo` attribute will automatically initialize once the DOM is ready. This method is convenient for quick setup via CDN.

```html
<script src="https://fastly.jsdelivr.net/npm/live-photo@latest"></script>
<div data-live-photo data-photo-src="photo.jpg" data-video-src="video.mp4"
     style="width: 320px; height: 320px"></div>
```

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

### Example Usage of extractFromLivePhoto and revoke

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/extractFromLivePhoto.md

Demonstrates how to use extractFromLivePhoto, display the extracted photo and video, and then revoke the object URLs to free memory.

```typescript
const result = await extractFromLivePhoto(file);
if (result) {
  // Create image and video elements
  const img = document.createElement('img');
  img.src = result.photoUrl;
  document.body.appendChild(img);

  const video = document.createElement('video');
  video.src = result.videoUrl;
  document.body.appendChild(video);

  // When done (after a timeout, user navigation, etc.)
  setTimeout(() => {
    result.revoke(); // Frees the object URLs
  }, 5000);
}
```

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

### Initialize LivePhotoViewer with Fully Custom Locale Labels

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/i18n.md

Provides an example of setting entirely custom labels for a specific locale, such as Japanese ('ja'), for full internationalization control.

```typescript
import { LivePhotoViewer } from 'live-photo';

const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  labels: {
    live: 'ライブ',
    enableAutoplay: '自動再生を有効にする',
    disableAutoplay: '自動再生を無効にする',
    mute: 'ミュート',
    unmute: 'ミュート解除',
  },
});
```

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

### Fully Customized Live Photo Viewer

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

A comprehensive example showing extensive customization options including dimensions, styling, autoplay, mute controls, theming, custom labels, and event handlers.

```typescript
new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  width: 400,
  height: 300,
  borderRadius: 12,
  autoplay: true,
  muted: true,
  showMuteButton: true,
  theme: 'dark',
  locale: 'en',
  labels: {
    live: 'ACTIVE',
    enableAutoplay: 'Play on hover',
    disableAutoplay: 'Stop autoplay',
    mute: 'Mute',
    unmute: 'Unmute',
  },
  storageKey: 'my-viewer',
  retryAttempts: 3,
  enableVibration: true,
  imageCustomization: {
    styles: { filter: 'brightness(1.1)' },
  },
  videoCustomization: {
    styles: { filter: 'saturate(1.1)' },
  },
  onPhotoLoad: (event, photo) => console.log('Photo loaded'),
  onVideoLoad: (duration) => console.log(`Video: ${duration}s`),
  onProgress: (progress) => console.log(`Buffered: ${progress}%`),
  onError: (error) => console.error(error),
});
```

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

### Handle Autoplay Policy with Muted Playback

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/errors.md

Demonstrates how to handle browser autoplay policies by starting the video muted. If playback fails due to autoplay restrictions, it prompts the user to enable sound, which is necessary for unmuted playback.

```typescript
const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  muted: true, // Start muted to allow autoplay
  onError: (error) => {
    if (error.type === 'PLAYBACK_ERROR') {
      // User gesture required for unmuted playback
      showMessage('Please click to enable sound');
    }
  },
});
```

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

### autoInit System

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/FILE_MANIFEST.md

System for declarative initialization of Live Photo elements using data attributes.

```APIDOC
## autoInit System

### Description
Enables declarative initialization of Live Photo elements on a page using `data-live-photo` attributes.

### Functions Documented
- **autoInit(root, selector)**: Initializes Live Photo elements within a specified root and selector.
- **AUTO_INIT_SELECTOR**: Constant defining the default selector for auto-initialization.

### Data Attributes
- **data-photo-src, data-video-src**: Required attributes for specifying media sources.
- Additional optional attributes for customization and behavior control.
- Rules for boolean, dimension, and sync group parsing.

### Format
- Function signature and behavior description.
- Reference table for data attributes.
- Explanation of attribute parsing rules.
- Usage examples covering various scenarios like sync, persistence, and lazy-loading.
- Guidance on accessing instances after initialization and comparing declarative vs. imperative approaches.
```

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

### autoInit()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Scans the DOM for elements with `[data-live-photo]` attribute and initializes LivePhotoViewer instances for each one. It is SSR safe and idempotent.

```APIDOC
## autoInit()

### Description
Scans the DOM for elements with `[data-live-photo]` attribute and initializes LivePhotoViewer instances for each one. It is SSR safe and idempotent.

### Method
```typescript
export function autoInit(
  root?: ParentNode,
  selector?: string
): LivePhotoViewer[]
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| root | `ParentNode` | No | `document` | DOM subtree to scan |
| selector | `string` | No | `'[data-live-photo]'` | CSS selector for elements to initialize |

### Returns
`LivePhotoViewer[]` - Array of newly created viewer instances

### Behavior
1. Scans the provided root (or entire document) for elements matching the selector
2. Skips elements already initialized (have `data-live-photo-initialized` attribute)
3. Parses `data-*` attributes into `LivePhotoOptions`
4. Creates a new `LivePhotoViewer` for each valid element
5. Marks initialized elements with `data-live-photo-initialized="true"`
6. Stores the instance reference on the element (internal key `__livePhotoViewer`)
7. Returns array of newly created instances

### Error Handling
If an element is missing required attributes or has invalid values:
- Logs a warning to console
- Skips that element
- Continues with other elements

### Example
```typescript
// Initialize all [data-live-photo] elements on the page
const viewers = autoInit();
console.log(`Initialized ${viewers.length} viewers`);

// Initialize only within a specific container
const viewers = autoInit(document.getElementById('gallery'));

// Custom selector
const viewers = autoInit(document, '.my-live-photos');
```
```

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

### onLoadStart

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Fired when the video load begins, particularly relevant in lazy loading scenarios.

```APIDOC
## onLoadStart

### Description
Fired when video load begins (in lazy mode).

### Parameters
None
```

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

### Basic Declarative Viewer Initialization

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Initializes a single Live Photo viewer using data attributes for photo and video sources. Ensure the live-photo script is included.

```html
<div data-live-photo
     data-photo-src="photo.jpg"
     data-video-src="video.mp4"
     style="width: 300px; height: 300px;"></div>

<script src="https://fastly.jsdelivr.net/npm/live-photo@latest"></script>
<script>
  import { autoInit } from 'live-photo';
  autoInit();
</script>
```

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

### Enable Haptic Vibration

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Enables haptic vibration feedback on supported devices when playback starts. Defaults to true.

```typescript
enableVibration?: boolean
```

```typescript
enableVibration: true   // Haptic feedback on play (default)
enableVibration: false  // Disable vibration
```

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

### pause()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/LivePhotoViewer.md

Pauses video playback without resetting to the start or hiding the video. The current video position is preserved.

```APIDOC
## pause()

### Description
Pauses video playback without resetting to the start or hiding the video. The video position is preserved.

### Method
`pause(): void`

### Returns
`void`

### Behavior
- Stops the internal playback state.
- Calls `video.pause()` on the underlying video element.
- Removes the `playing` class from the container.
- Keeps the photo hidden.

### Example
```typescript
viewer.pause();
```
```

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

### Example Usage of IS_MOBILE

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/helpers.md

Demonstrates how to import and use the IS_MOBILE constant to conditionally log messages based on device type.

```typescript
import { IS_MOBILE } from 'live-photo/utils/helpers';

if (IS_MOBILE) {
  console.log('Device has touch input');
} else {
  console.log('Desktop device');
}
```

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

### MP4 Extraction Algorithm

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/extractFromLivePhoto.md

The algorithm locates the 'ftyp' atom to determine the start of the MP4 data, treating all preceding data as JPEG.

```text
1. Searches backward from the end of the file for the `ftyp` atom (bytes: `0x66 0x74 0x79 0x70`)
2. The 4 bytes before `ftyp` contain the box size, so the actual MP4 start is `ftypPos - 4`
3. Data from 0 to the MP4 start is treated as JPEG
4. Data from MP4 start to end is treated as MP4
```

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

### Accessing Live Photo Viewer Instances After Auto-Init

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Demonstrates how to retrieve an array of all initialized Live Photo viewer instances after calling autoInit, and how to access individual viewer states or control them programmatically.

```javascript
import { autoInit } from 'live-photo';

const viewers = autoInit();

// Get the state of each viewer
viewers.forEach(viewer => {
  const state = viewer.getState();
  console.log('Autoplay:', state.autoplay);
});

// Or retrieve a specific element's viewer instance
const element = document.querySelector('[data-live-photo]');
const viewer = element.__livePhotoViewer; // Internal property
viewer.play();
```

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

### LivePhotoViewer with Explicit PreferencesStore

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Demonstrates initializing LivePhotoViewer with an explicitly provided PreferencesStore instance, which takes the highest priority.

```typescript
// Priority 1: Explicit store
const customStore = createMemoryStore();
const viewer1 = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container1'),
  preferencesStore: customStore,
});
```

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

### Auto-initialize Live Photo Viewers

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Demonstrates how to automatically initialize Live Photo viewers using the `autoInit` function. You can either call it without arguments to use the default selector or provide a specific document and selector.

```typescript
import { autoInit, AUTO_INIT_SELECTOR } from 'live-photo';

// Both are equivalent:
const viewers1 = autoInit();
const viewers2 = autoInit(document, AUTO_INIT_SELECTOR);
```

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

### Debounce Resize Handler

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/debounce.md

Debounces a resize event handler to limit expensive layout calculations. Includes an example of how to cancel the debounced function.

```typescript
import { debounce } from 'live-photo/utils/debounce';

const handleResize = debounce(() => {
  console.log('Window resized');
  // Expensive layout calculation
}, 300);

window.addEventListener('resize', handleResize);

// Cleanup
window.addEventListener('resize', () => {
  handleResize.cancel();
});
```

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

### LivePhotoViewer Constructor

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/LivePhotoViewer.md

Initializes a new LivePhotoViewer instance with the provided configuration options. This constructor validates options, sets up internal components, and prepares the viewer for displaying Live Photos.

```APIDOC
## LivePhotoViewer Constructor

### Description
Creates a new LivePhotoViewer instance. Validates options, initializes internal managers, assembles DOM elements, sets up event listeners, and configures preference persistence.

### Method
constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (`LivePhotoOptions`) - Required - Configuration object for the viewer

### Request Example
```typescript
const viewer = new LivePhotoViewer({
  photoSrc: "path/to/photo.jpg",
  videoSrc: "path/to/video.mp4",
  container: document.getElementById("viewer-container")
});
```

### Response
#### Success Response
None (constructor)

#### Response Example
None

### Throws
- `Error` if `photoSrc`, `videoSrc`, or `container` are missing
- `Error` if `container` is not a valid `HTMLElement`
- `Error` if `longPressDelay` or `retryAttempts` are negative
- `Error` if `width` or `height` are non-positive values
- `Error` if `storageKey` is an empty string
```

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

### Manual `autoInit()` Call in Bundled Projects

Source: https://github.com/iceywu/live-photo/blob/main/docs/auto-init.md

In bundled projects using `import`, you must manually call `autoInit()` once to scan for `data-live-photo` elements. This function can scan the entire document or a specific container.

```javascript
import { autoInit } from 'live-photo';

autoInit();            // Scan the entire document for data-live-photo elements
autoInit(myContainer); // Scan only a specific subtree
```

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

### Get Current Preferences

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Retrieves a snapshot of the current preferences. The returned object may contain optional `autoplay` and `muted` boolean fields.

```typescript
get(): LivePhotoPrefs
```

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

### Declarative HTML Initialization for Live Photo

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/INDEX.md

Set up Live Photo Viewer directly in HTML using data attributes and the autoInit function for automatic initialization.

```html
<div data-live-photo
     data-photo-src="photo.jpg"
     data-video-src="video.mp4"
     data-locale="en"
     style="width: 300px; height: 300px;"></div>

<script src="https://fastly.jsdelivr.net/npm/live-photo@latest"></script>
<script>
  import { autoInit } from 'live-photo';
  autoInit();
</script>
```

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

### Example Usage of createLivePhotoError

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/helpers.md

Shows how to import and use createLivePhotoError to generate a structured error object for video load failures, including an original error.

```typescript
import { createLivePhotoError } from 'live-photo/utils/helpers';

const error = createLivePhotoError(
  'VIDEO_LOAD_ERROR',
  'Failed to fetch video from CDN',
  new Error('Network timeout')
);

console.log(error.type);           // 'VIDEO_LOAD_ERROR'
console.log(error.message);        // 'Failed to fetch video from CDN'
console.log(error.originalError);  // Error: Network timeout
```

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

### Get LivePhotoViewer State

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/LivePhotoViewer.md

Retrieves a frozen snapshot of the current playback and preference state, including playing status, autoplay, mute, and error states.

```typescript
const state = viewer.getState();
console.log(state.isPlaying); // true or false
console.log(state.muted);     // true or false
```

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

### onLoadStart Callback

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Fired when the video load begins, specifically in lazy loading mode. This callback takes no arguments.

```typescript
onLoadStart?: () => void
```

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

### Cancel Pending Execution Example

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/debounce.md

Shows how to use the `cancel` method on a debounced function to prevent a pending execution from occurring. This is useful for aborting scheduled operations.

```typescript
const debounced = debounce(() => console.log('Done'), 1000);

debounced(); // Scheduled for 1000ms

// Cancel before execution
debounced.cancel();
// "Done" is never logged
```

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

### LivePhotoViewer with Shared Memory and Persistent Storage

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Demonstrates initializing LivePhotoViewer with both syncGroup and storageKey for a combined shared memory and persistent store.

```typescript
// Priority 2: Both syncGroup and storageKey
const viewer4 = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container4'),
  syncGroup: 'gallery',
  storageKey: 'gallery-prefs',
});
```

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

### Initialize LivePhotoViewer with ES Module

Source: https://github.com/iceywu/live-photo/blob/main/README.md

Import and initialize the LivePhotoViewer when using ES Modules. Make sure the container element is available in the DOM.

```javascript
import { LivePhotoViewer } from 'live-photo';

const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
});
```

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

### Resolve Labels with Default Locale

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/i18n.md

Uses the resolveLabels function to get UI labels for a specified locale, defaulting to English. Demonstrates accessing standard labels.

```typescript
import { resolveLabels } from 'live-photo';

// Use English locale
const labels = resolveLabels('en');
console.log(labels.live);           // "LIVE"
console.log(labels.enableAutoplay); // "Enable autoplay"
```

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

### LivePhotoViewer with Shared Memory Store

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Shows how to initialize LivePhotoViewer using only a syncGroup, resulting in a shared memory store.

```typescript
// Priority 3: Only syncGroup
const viewer2 = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container2'),
  syncGroup: 'default',
});
```

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

### LivePhotoViewer with Persistent Storage

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Illustrates initializing LivePhotoViewer with only a storageKey, enabling persistent storage for preferences.

```typescript
// Priority 4: Only storageKey
const viewer3 = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container3'),
  storageKey: 'my-prefs',
});
```

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

### Manual Preference Management with LivePhotoViewer

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/storage.md

Demonstrates how to manually load preferences from localStorage before initializing a LivePhotoViewer and how to save updated preferences when a setting like mute changes. Ensure preferences are loaded using `loadPrefs` and saved using `savePrefs`.

```typescript
import { loadPrefs, savePrefs } from 'live-photo';

// Load saved preferences
const saved = loadPrefs('gallery');

// Create viewer with loaded preferences
const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  autoplay: saved.autoplay ?? true,
  muted: saved.muted ?? true,
  onMutedChange: (muted) => {
    savePrefs('gallery', { muted });
  },
});
```

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

### Fallback to Default Locale Example

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/i18n.md

Illustrates how to use the DEFAULT_LOCALE to provide a fallback set of labels when a user's requested locale is not available in LOCALE_LABELS. This ensures UI consistency.

```typescript
import { DEFAULT_LOCALE, LOCALE_LABELS } from 'live-photo';

// If user's locale is not in LOCALE_LABELS, fall back to default
const labels = LOCALE_LABELS[userLocale] || LOCALE_LABELS[DEFAULT_LOCALE];
```

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

### Debounce Usage Example

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/debounce.md

Demonstrates how to use the debounce function to limit the execution of an expensive operation. Only the last invocation within the wait period triggers the actual function call.

```typescript
import { debounce } from 'live-photo/utils/debounce';

const expensiveOperation = (value) => {
  console.log('Processing:', value);
};

const debouncedOp = debounce(expensiveOperation, 500);

// Call multiple times
debouncedOp('a');
debouncedOp('b');
debouncedOp('c');

// Only 'c' is logged, 500ms after the last call
// Output (after 500ms): Processing: c
```

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

### createVideo()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/UIComponents.md

Creates the video element with player configuration, allowing customization of styles, muted state, and preload strategy.

```APIDOC
## createVideo()

### Description
Creates the video element with player configuration.

### Method
createVideo

### Parameters
#### Function Parameters
- **customization** (ElementCustomization) - Optional - Custom styles and attributes
- **muted** (boolean) - Optional - Default: `true` - Initial muted state
- **preload** ('auto' | 'metadata' | 'none') - Optional - Default: `'metadata'` - Preload strategy

### Returns
- **element** (HTMLVideoElement) - The `<video>` element
- **cleanup** (() => void) - Function to remove prevent-default listeners

### Example
```typescript
const videoResult = createVideo(
  { styles: { filter: 'brightness(0.9)' } },
  false, // unmuted
  'metadata'
);

const video = videoResult.element;
console.log(video.muted); // false
console.log(video.preload); // "metadata"

videoResult.cleanup();
```
```

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

### Configure Audio Muting

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Set whether audio starts muted. This is useful for enabling autoplay in browsers with strict policies. The user can toggle the mute state via the menu.

```typescript
muted: true   // Start silent (allows autoplay)
muted: false  // Start with sound
```

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

### Initialize LivePhotoViewer via CDN

Source: https://github.com/iceywu/live-photo/blob/main/README.md

Use this snippet to initialize the LivePhotoViewer when using a CDN. Ensure the container element exists in the DOM.

```html
<script src="https://fastly.jsdelivr.net/npm/live-photo@latest"></script>
<div id="container"></div>
<script>
  new LivePhotoViewer({
    photoSrc: 'photo.jpg',
    videoSrc: 'video.mp4',
    container: document.getElementById('container'),
  });
</script>
```

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

### Initialize LivePhotoViewers

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Demonstrates how to initialize all LivePhotoViewer instances on a page or within a specific container using custom selectors.

```typescript
// Initialize all [data-live-photo] elements on the page
const viewers = autoInit();
console.log(`Initialized ${viewers.length} viewers`);

// Initialize only within a specific container
const viewers = autoInit(document.getElementById('gallery'));

// Custom selector
const viewers = autoInit(document, '.my-live-photos');
```

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

### getSharedStore

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Gets or lazily creates a shared named store for synchronizing preferences across multiple viewers using the syncGroup option. The same store instance is reused for all viewers with the same group name.

```APIDOC
## getSharedStore(name: string)

### Description
Gets or lazily creates a shared named store for synchronizing preferences across multiple viewers using the `syncGroup` option.

### Method
`getSharedStore`

### Parameters
#### Path Parameters
- **name** (string) - Yes - Unique identifier for the sync group

### Returns
`PreferencesStore` - A shared memory store (same instance returned for the same name)

### Details
This is used internally when the `syncGroup` option is provided to LivePhotoViewer:
- The same store instance is reused for all viewers with the same group name
- Stores are cached globally; calling twice with the same name returns the same instance
- Useful for synchronizing viewers across different parts of the page without explicit store passing

### Example:
```typescript
const viewer1 = new LivePhotoViewer({
  photoSrc: 'photo1.jpg',
  videoSrc: 'video1.mp4',
  container: document.getElementById('container1'),
  syncGroup: 'gallery',
});

const viewer2 = new LivePhotoViewer({
  photoSrc: 'photo2.jpg',
  videoSrc: 'video2.mp4',
  container: document.getElementById('container2'),
  syncGroup: 'gallery', // Same group name = shared store
});

// Preferences are synchronized
viewer1.setMuted(true);
console.log(viewer2.getState().muted); // true
```
```

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

### Initialize LivePhotoViewer with Built-in Locale

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/i18n.md

Demonstrates how to initialize the LivePhotoViewer using a predefined locale, such as English ('en'). Ensure the 'live-photo' library is imported.

```typescript
import { LivePhotoViewer } from 'live-photo';

const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  locale: 'en', // Use English labels
});
```

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

### Get or Create Shared PreferencesStore

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/PreferencesStore.md

Use getSharedStore to obtain a shared memory store for synchronizing preferences across multiple viewers using the same sync group name. This ensures that all viewers within the same group share the same store instance, enabling seamless preference synchronization.

```typescript
export function getSharedStore(name: string): PreferencesStore
```

```typescript
const viewer1 = new LivePhotoViewer({
  photoSrc: 'photo1.jpg',
  videoSrc: 'video1.mp4',
  container: document.getElementById('container1'),
  syncGroup: 'gallery',
});

const viewer2 = new LivePhotoViewer({
  photoSrc: 'photo2.jpg',
  videoSrc: 'video2.mp4',
  container: document.getElementById('container2'),
  syncGroup: 'gallery', // Same group name = shared store
});

// Preferences are synchronized
viewer1.setMuted(true);
console.log(viewer2.getState().muted); // true
```

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

### LivePhotoOptions

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/types.md

Configuration object for creating a `LivePhotoViewer` instance. All callback functions are optional.

```APIDOC
## LivePhotoOptions

### Description
Configuration object for creating a `LivePhotoViewer` instance. All callback functions are optional.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **photoSrc** (string) - Required - URL of the static photo image
- **videoSrc** (string) - Required - URL of the video file (MP4 recommended)
- **container** (HTMLElement) - Required - DOM element to mount the viewer
- **width** (number | string) - Optional - Viewer width (px or CSS units). Default: `'300px'`
- **height** (number | string) - Optional - Viewer height (px or CSS units). Default: `'300px'`
- **autoplay** (boolean) - Optional - Play on hover (desktop) or long-press (mobile). Default: `true`
- **lazyLoadVideo** (boolean) - Optional - Load video only when in viewport. Default: `false`
- **longPressDelay** (number) - Optional - Long-press threshold in milliseconds. Default: `300`
- **muted** (boolean) - Optional - Start with audio muted. Default: `true`
- **showMuteButton** (boolean) - Optional - Show mute/unmute button in menu. Default: `true`
- **borderRadius** (number | string) - Optional - Corner radius (px or CSS units).
- **locale** (string) - Optional - UI language code. Default: `'zh-CN'`
- **labels** (Partial<LivePhotoLabels>) - Optional - Override individual UI labels.
- **storageKey** (string) - Optional - localStorage key for persistence.
- **syncGroup** (string) - Optional - Named group for preference sharing.
- **preferencesStore** (PreferencesStore) - Optional - Custom preference store.
- **theme** ('light' | 'dark' | 'auto') - Optional - UI color theme.
- **preload** ('auto' | 'metadata' | 'none') - Optional - Video preload strategy. Default: `'metadata'`
- **retryAttempts** (number) - Optional - Retry count on load failure. Default: `3`
- **enableVibration** (boolean) - Optional - Haptic feedback on play. Default: `true`
- **staticBadgeIcon** (boolean) - Optional - Disable slash animation. Default: `false`
- **imageCustomization** (ElementCustomization) - Optional - Custom styles/attributes for photo.
- **videoCustomization** (ElementCustomization) - Optional - Custom styles/attributes for video.

### Callbacks
All callbacks are optional. Parameters are passed in the order shown:

- **onPhotoLoad** - Triggered when the photo image is loaded. Parameters: `(event: Event, photo: HTMLImageElement)`
- **onVideoLoad** - Triggered when video metadata is ready. Parameters: `(duration: number, event: Event, video: HTMLVideoElement)`
- **onCanPlay** - Triggered when the video is ready to play. Parameters: `(event: Event, video: HTMLVideoElement)`
- **onLoadStart** - Triggered when the video load begins (in lazy mode). Parameters: `()`
- **onLoadProgress** - Triggered during download progress (in bytes). Parameters: `(loaded: number, total: number)`
- **onProgress** - Triggered during buffer progress (0–100). Parameters: `(progress: number, event: Event, video: HTMLVideoElement)`
- **onEnded** - Triggered when playback finishes. Parameters: `(event: Event, video: HTMLVideoElement)`
- **onClick** - Triggered on a short click/tap on the viewer. Parameters: `(event: Event)`
- **onMutedChange** - Triggered when the mute state changes. Parameters: `(muted: boolean, video: HTMLVideoElement)`
- **onError** - Triggered on a load or playback error. Parameters: `(error: LivePhotoError, event?: Event)`

### Request Example
None

### Response
None
```

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

### LivePhotoViewer Constructor

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/LivePhotoViewer.md

Initializes a new LivePhotoViewer instance. It validates options, sets up internal managers, builds the DOM, configures event listeners, and manages preference persistence. Ensure 'photoSrc', 'videoSrc', and 'container' are provided and valid.

```typescript
constructor(options: LivePhotoOptions)
```

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

### Live Photo Viewer with Localization and Theme

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Initializes a Live Photo viewer with specific localization (language) and theme (dark mode) settings applied via data attributes. Ensure the live-photo script is included.

```html
<div data-live-photo
     data-photo-src="photo.jpg"
     data-video-src="video.mp4"
     data-locale="en"
     data-theme="dark"
     style="width: 300px; height: 300px;"></div>

<script src="https://fastly.jsdelivr.net/npm/live-photo@latest"></script>
<script>
  import { autoInit } from 'live-photo';
  autoInit();
</script>
```

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

### Public Methods

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/GENERATION_SUMMARY.txt

The LivePhoto library exposes several public methods for controlling playback, managing mute state, retrieving the current state, and cleaning up resources.

```APIDOC
## Public Methods

### play()

### pause()

### stop()

### toggle()

### setMuted(muted: boolean)

### toggleMute()

### getState()

### destroy()
```

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

### Project File Structure

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/FILE_MANIFEST.md

Overview of the directory structure for the Live Photo project's documentation and source files.

```tree
/workspace/home/output/
├── README.md                     [Start here - Documentation guide]
├── INDEX.md                      [API overview and navigation]
├── FILE_MANIFEST.md              [This file]
├── GENERATION_SUMMARY.txt        [Generation details]
├── types.md                      [Type definitions]
├── configuration.md              [Config options]
├── errors.md                     [Error handling]
└── api-reference/
    ├── LivePhotoViewer.md        [Main class]
    ├── PreferencesStore.md       [Preference store functions]
    ├── UIComponents.md           [UI component functions]
    ├── autoInit.md               [Declarative initialization]
    ├── extractFromLivePhoto.md   [File extraction]
    ├── i18n.md                   [Localization]
    ├── storage.md                [Storage utilities]
    ├── helpers.md                [Helper functions]
    └── debounce.md               [Debounce utility]

```

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

### Declarative Auto-Initialization

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/INDEX.md

Functionality for automatically initializing Live Photo viewers on elements matching a specific selector.

```APIDOC
## Declarative Auto-Initialization

### `autoInit()`
- **Purpose:** Auto-initialize elements with `[data-live-photo]` attributes.

### `AUTO_INIT_SELECTOR` (Constant)
- **Purpose:** Default selector used for auto-initialization: `'[data-live-photo]'`.
```

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

### General Constructor Error Handling

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/errors.md

A general pattern for catching synchronous errors during LivePhotoViewer initialization. This approach is crucial for handling invalid options before the viewer is fully created and ensures errors are managed appropriately, such as informing the user or retrying the operation.

```typescript
let viewer;

try {
  viewer = new LivePhotoViewer({
    photoSrc: options.photo,
    videoSrc: options.video,
    container: targetElement,
    width: options.width,
    height: options.height,
  });
} catch (error) {
  console.error('Invalid options:', error.message);
  // Show error to user, fix options, retry
}
```

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

### autoInit() Function Signature

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/autoInit.md

Defines the signature for the autoInit function, specifying optional root and selector parameters.

```typescript
export function autoInit(
  root?: ParentNode,
  selector?: string
): LivePhotoViewer[]
```

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

### PreferencesStore

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/types.md

Abstraction for managing the persistence and synchronization of live photo preferences.

```APIDOC
## PreferencesStore

### Description
Provides methods to get, set, and subscribe to changes in live photo preferences.

### Methods

- **get()**: Retrieves the current preferences snapshot. Returns `LivePhotoPrefs`.
- **set(patch: LivePhotoPrefs)**: Updates preferences with a partial object. Returns `void`.
- **subscribe(listener: (prefs: LivePhotoPrefs) => void)**: Registers a listener function to be called when preferences change. Returns a function to unsubscribe the listener.
```

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

### Responsive Viewer Configuration

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/helpers.md

Sets up responsive dimensions and vibration settings for LivePhotoViewer based on whether the device is mobile.

```typescript
import { IS_MOBILE } from 'live-photo';

function configureViewer(container) {
  return new LivePhotoViewer({
    photoSrc: 'photo.jpg',
    videoSrc: 'video.mp4',
    container,
    width: IS_MOBILE ? '100%' : 400,
    height: IS_MOBILE ? '100%' : 300,
    enableVibration: IS_MOBILE, // Vibration only on touch devices
  });
}
```

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

### createDropMenu()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/UIComponents.md

Creates the dropdown menu with autoplay and mute toggle buttons. The menu is hidden by default and shown when the badge is clicked.

```APIDOC
## createDropMenu()

### Description
Creates the dropdown menu with autoplay and mute toggle buttons. The menu is hidden by default and shown when the badge is clicked.

### Method
`createDropMenu`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **autoplay** (`boolean`) - Required - Initial autoplay state
- **options** (`object`) - Optional - Menu configuration
  - **options.muted** (`boolean`) - Optional - Initial muted state
  - **options.showMuteButton** (`boolean`) - Optional - Whether to show mute button
  - **options.labels** (`LivePhotoLabels`) - Optional - UI text labels

### Returns
`HTMLDivElement` - The menu element with class `dropdown-menu`

### Details
- The menu has role `menu` and contains buttons with role `menuitem`.
- Always includes autoplay toggle button (id: `toggle-autoplay`).
- Includes mute toggle button only if `showMuteButton` is true (id: `toggle-mute`).
- Is keyboard-navigable (arrow keys, Escape to close).

### Example
```typescript
const menu = createDropMenu(true, {
  muted: false,
  showMuteButton: true,
  labels: {
    live: 'LIVE',
    enableAutoplay: 'Enable autoplay',
    disableAutoplay: 'Disable autoplay',
    mute: 'Mute',
    unmute: 'Unmute',
  },
});

console.log(menu.className); // "dropdown-menu"
console.log(menu.querySelectorAll('button').length); // 2 (autoplay + mute)
```
```

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

### createBadge()

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/UIComponents.md

Creates the "LIVE" badge displayed in the corner of the viewer, configurable for autoplay state, static icon, and custom text label.

```APIDOC
## createBadge()

### Description
Creates the "LIVE" badge displayed in the corner of the viewer.

### Method
createBadge

### Parameters
#### Function Parameters
- **autoplay** (boolean) - Required - Initial autoplay state
- **staticIcon** (boolean) - Optional - Default: `false` - Disable slash icon animation
- **liveText** (string) - Optional - Default: `'LIVE'` - Badge text label

### Returns
- **element** (HTMLDivElement) - The badge element with class `live-photo-badge`

### Example
```typescript
const badge = createBadge(true, false, '实况');
console.log(badge.className); // "live-photo-badge"
console.log(badge.getAttribute('role')); // "button"
```
```

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

### onLoadProgress

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Fired to report download progress in bytes, indicating how many bytes have been loaded and the total expected bytes.

```APIDOC
## onLoadProgress

### Description
Fired for download progress (bytes).

### Parameters
- `loaded` (number) - Required - Bytes downloaded
- `total` (number) - Required - Total bytes
```

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

### Configure Responsive Gallery

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/configuration.md

Use this configuration for a responsive gallery where the viewer takes up the full width and height of its container. Enables lazy loading for videos.

```typescript
new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('item'),
  width: '100%',
  height: '100%',
  lazyLoadVideo: true,
  syncGroup: 'gallery',
});
```

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

### Initialize LivePhotoViewer with Custom Labels

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/api-reference/i18n.md

Shows how to override specific UI text labels by providing a custom 'labels' object during LivePhotoViewer initialization. This allows for direct text customization.

```typescript
import { LivePhotoViewer } from 'live-photo';

const viewer = new LivePhotoViewer({
  photoSrc: 'photo.jpg',
  videoSrc: 'video.mp4',
  container: document.getElementById('container'),
  labels: {
    live: 'RECORDING',
    mute: 'Silence',
    unmute: 'Sound',
  },
});
```

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

### UI Components Creation

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/FILE_MANIFEST.md

Functions for creating various UI elements for Live Photo integration.

```APIDOC
## UI Components Creation

### Description
Functions to programmatically create UI components for displaying Live Photos and related controls.

### Functions Documented
- **createContainer(options)**: Creates the root element for UI.
- **createPhoto(src, customization)**: Creates a photo element.
- **createVideo(customization, muted, preload)**: Creates a video element.
- **createBadge(autoplay, staticIcon, liveText)**: Creates a badge element.
- **createDropMenu(autoplay, options)**: Creates a dropdown menu element.
- **createProgressBar()**: Creates a progress bar element.
- **createOverlay()**: Creates a click/touch overlay element.
- **updateBadgeContent()**: Updates the content of a badge.
- **updateAutoplayButton()**: Updates the state of the autoplay button.
- **updateMuteButton()**: Updates the state of the mute button.

### Type
- **ElementCustomization**: Interface for customizing element appearance and behavior.

### Format
- Function signatures with parameters.
- Explanation of return types.
- Details about element structure and customization options.
- Includes usage examples and patterns.
```

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

### Helper Utilities

Source: https://github.com/iceywu/live-photo/blob/main/_autodocs/FILE_MANIFEST.md

Helper functions for device detection and error creation.

```APIDOC
## Helper Utilities

### Description
Provides utility constants and functions for device detection and creating custom error objects.

### Exports Documented
- **IS_MOBILE**: Constant indicating if the current device is mobile.
- **createLivePhotoError()**: Function to create Live Photo-specific error objects.

### Format
- Definition and behavior of constants.
- Function signature.
- Explanation of the device detection strategy.
- Usage examples for device-specific behavior, responsive configurations, error handling, and feature detection.
```