react-native-ensys-camera-x 1.0.7

package/README.md

@@ -0,0 +1,833 @@
+# react-native-ensys-camera-x
+
+A full-screen native Android camera for React Native. One call opens a WhatsApp-style camera —
+photo/video capture, gallery multi-select, and an editor (crop, rotate, filters, stickers, emoji,
+text, drawing, trim) — and gives you back the media the user picked.
+
+**A complete media library screen is included.** `<CameraMediaLibrary />` is a single element that
+renders a whole media app: the gallery grid with category tabs, a swipeable pager, the Plus/Cross
+button, a full-screen viewer with a video scrubber, in-app document and audio previews, an audio
+recorder, an encrypted store that survives restarts, and upload progress notifications.
+
+**Every icon is customizable** from a single configuration object, and any icon you don't replace
+keeps the one the plugin ships.
+
+See [ICON_CUSTOMIZATION.md](ICON_CUSTOMIZATION.md) for React component, image, Android
+resource, tint, and inline SVG examples and surface limitations.
+
+**Every string is translatable.** Pass your app's active language and the plugin follows it — right
+down to the native camera, with right-to-left languages handled automatically.
+
+> **Android only.** The iOS APIs exist as typed stubs that reject with an unsupported-platform
+> error, so cross-platform code still compiles.
+
+---
+
+## Requirements
+
+| | |
+| --- | --- |
+| React Native | 0.85 (New Architecture, which is the default) |
+| Node | 20 or newer |
+| JDK | 17 |
+| Android | minSdk 24 |
+
+---
+
+## Step 1 — Create a React Native project
+
+Skip this if you already have an app.
+
+```sh
+npx @react-native-community/cli@latest init MyApp --version 0.85.0
+cd MyApp
+```
+
+---
+
+## Step 2 — Install the plugin
+
+```sh
+npm install react-native-ensys-camera-x react-native-sqlcipher
+```
+
+That's the whole setup. Autolinking wires up the native code, and camera / microphone / gallery
+permissions are declared and requested by the plugin itself — **you do not need to edit any Android
+file.**
+
+`react-native-sqlcipher` is the encrypted store behind the media library screen you add in Step 3.
+If you only ever call `openCameraPicker()` yourself, leave it out — the camera doesn't use it.
+
+---
+
+## Step 3 — Add this one file
+
+Open the file your project already has at:
+
+```
+MyApp/App.tsx
+```
+
+Delete everything in it and paste this in. This single file is your whole integration: the plugin
+configuration, your icon customizations, and the complete media library screen.
+
+```tsx
+/**
+ * App.tsx — react-native-ensys-camera-x
+ *
+ * Everything you need is in this one file:
+ *   1. CUSTOM_ICONS  — replace any default icon with your own
+ *   2. MY_LANGUAGES  — translate the plugin into your app's languages
+ *   3. configureCameraPlugin — plugin settings
+ *   4. App — the complete media library screen
+ */
+import {
+  CameraMediaLibrary,
+  configureCameraPlugin,
+  type CameraAsset,
+  type CameraIconsConfig,
+  type CameraTranslationBundles,
+} from 'react-native-ensys-camera-x';
+
+// ══════════════════════════════════════════════════════════════════════════
+//  1. CUSTOM ICONS  ←  replace any default icon here
+//
+//  Every key is optional. Leave a key out and the plugin's own icon is used.
+//  See the "Icon keys" table in the README for the full list of keys.
+//
+//  Five ways to customize an icon:
+//    myKey: require('./assets/my-icon.png')   → your image (React Native UI)
+//    myKey: MyIconComponent                   → your React component
+//    myKey: { tintColor: '#25D366' }          → recolour the built-in icon
+//    myKey: { resourceName: 'my_drawable' }   → your Android drawable
+//                                               (native camera screen)
+//    myKey: { svg: '<svg …>…</svg>' }          → inline SVG markup (both surfaces)
+// ══════════════════════════════════════════════════════════════════════════
+const CUSTOM_ICONS: CameraIconsConfig = {
+  // ---- Uncomment and edit any of these, or add your own ----
+  // send: { tintColor: '#25D366' },
+  // flashOn: require('./assets/flash-on.png'),
+  // crop: { resourceName: 'my_crop_icon' },
+};
+
+// ══════════════════════════════════════════════════════════════════════════
+//  2. LANGUAGES  ←  optional; delete this block to stay in English
+//
+//  One entry per language your app supports, keyed by language code
+//  ('es', 'fr', 'pt-BR', 'zh-Hans', …). Every string is optional — anything
+//  you don't translate stays English. Right-to-left languages (Arabic,
+//  Persian, Hebrew, Urdu …) flip the layout automatically.
+//
+//  See the "Languages" section in the README for the full list of text keys.
+// ══════════════════════════════════════════════════════════════════════════
+const MY_LANGUAGES: CameraTranslationBundles = {
+  es: { done: 'Listo', cancel: 'Cancelar', photoMode: 'Foto', videoMode: 'Video' },
+  ar: { done: 'تم', cancel: 'إلغاء', photoMode: 'صورة', videoMode: 'فيديو' },
+};
+
+// ══════════════════════════════════════════════════════════════════════════
+//  3. PLUGIN CONFIGURATION
+// ══════════════════════════════════════════════════════════════════════════
+configureCameraPlugin({
+  customIcons: CUSTOM_ICONS,
+  theme: 'default', // 'default' | 'dark' | 'light' | 'minimal'
+
+  translations: MY_LANGUAGES,
+  language: 'en', // your app's active language.
+  //                Switch it any time with setCameraLanguage('es') — the whole
+  //                plugin updates immediately, no restart needed.
+  //
+  //                Or hand `language` a provider instead of a code and the plugin
+  //                follows your app's language on its own, forever after:
+  //                  language: { get: () => i18n.language,
+  //                              subscribe: (cb) => { i18n.on('languageChanged', cb);
+  //                                                   return () => i18n.off('languageChanged', cb) } }
+  //                See "Follow your app's language automatically" in the README.
+});
+
+// ══════════════════════════════════════════════════════════════════════════
+//  4. YOUR SCREEN
+//
+//  One element renders the whole media app: the gallery grid with its category
+//  tabs, the Plus button (camera / gallery / documents / audio / recorder), the
+//  full-screen viewer, and the encrypted store that keeps your media between
+//  launches. Every prop is optional.
+// ══════════════════════════════════════════════════════════════════════════
+export default function App() {
+  return (
+    <CameraMediaLibrary
+      // Where media is POSTed when the user presses Send, which is what drives
+      // the upload notifications. Leave it out and nothing is uploaded —
+      // everything else behaves exactly the same.
+      // uploadUrl="https://api.example.com/upload"
+
+      // Which category tab opens first:
+      // 'all' | 'photos' | 'videos' | 'documents' | 'audio'
+      initialFilter="all"
+      // Called whenever the library changes, so your own screens can follow it.
+      onAssetsChange={(assets: CameraAsset[]) => {
+        console.log(`${assets.length} items in the library`);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Step 4 — Run the app
+
+```sh
+npm run android
+```
+
+Tap the **+** button, then **Camera**. Take a photo or video — or pick from the gallery, edit it and
+press send — and it lands in the grid and stays there between launches. Tap a tile to open the
+full-screen viewer.
+
+---
+
+## Media library screen
+
+`<CameraMediaLibrary />` is the screen from Step 3 — a complete media app in one element:
+
+- **Gallery grid** with five category tabs (All, Photos, Videos, Documents, Audio) and a swipeable
+  pager between them
+- **Plus/Cross button** that opens the camera, the gallery editor, the document picker, the audio
+  picker, or the audio recorder
+- **Full-screen viewer** you swipe through, with a video scrubber, a position counter, a details
+  sheet, and delete / share actions
+- **In-app document and audio previews** (PDF, Word, Excel, PowerPoint, text, images …) plus a mini
+  audio player that keeps playing as you browse
+- **Encrypted storage** — media is kept in a SQLCipher database, so the library survives app restarts
+- **Upload progress** in the system notification bar, once you set `uploadUrl`
+
+**Every readout follows the host language.** The dates, times, file sizes, durations, resolutions
+and the `3 / 12` position counter — in the grid rows, the full-screen viewer and the details sheet —
+are formatted for the active language automatically: localized month names, a 12- or 24-hour clock,
+the locale's decimal separator, and its own numerals (Arabic and Persian show their digits). There
+is nothing to configure. The size-unit labels (`B`, `KB`, `MB`, `GB`) are themselves translation
+keys, so those localize too when you provide them.
+
+| Prop | Meaning |
+| --- | --- |
+| `uploadUrl` | Where media is POSTed when the user presses Send. Omit it and nothing is uploaded — everything else is identical |
+| `initialFilter` | Category tab selected on first mount: `'all'` (default), `'photos'`, `'videos'`, `'documents'`, `'audio'` |
+| `onAssetsChange` | Called with the full asset list whenever the library changes (capture, pick, delete) |
+| `style` | Extra styles for the screen's root view |
+| `theme` | Same values as `configureCameraPlugin`'s `theme` |
+| `icons` | Icon overrides applied to this screen |
+| `locale`, `bundles` | Language and translations, if you prefer props over `configureCameraPlugin` |
+
+Configure language and icons through **either** `configureCameraPlugin` **or** these props — a
+`<CameraMediaLibrary />` with no props inherits whatever you configured, and localization props
+passed here take over instead of merging.
+
+This screen needs the `react-native-sqlcipher` package from Step 2, which is its encrypted store.
+The native camera doesn't: it bundles its own copy of SQLCipher, so `openCameraPicker()` works
+without it.
+
+### Using the pieces on their own
+
+Building your own screen instead? Every part is exported:
+
+```tsx
+import {
+  MediaLibraryScreen, // the same screen, without the providers wrapped around it
+  RecordAudioScreen, // the audio recorder
+  ImagePreview, // the viewer's slides, one per media kind
+  VideoPreview,
+  DocumentPreview,
+  AudioPreview,
+  MediaMetadataHeader, // the name / size / date header
+  ExpandableFab, // the Plus/Cross button
+  ViewerCounter, // the "3 / 12" position counter
+  DocumentTile, // the document and audio cards
+  AudioTile,
+  libraryPalette, // the shell's colours
+  wp, hp, ms, fs, // and its screen-scaling helpers
+} from 'react-native-ensys-camera-x';
+```
+
+---
+
+## How to use it
+
+Prefer to build your own UI? `openCameraPicker()` is the whole API you need:
+
+```tsx
+const result = await openCameraPicker({ mediaTypes: 'all', selectionLimit: 0 });
+
+if (!result.cancelled) {
+  result.assets.forEach((asset) => {
+    console.log(asset.uri);      // file:// path to the media
+    console.log(asset.type);     // 'photo' | 'video' | 'document' | 'audio'
+    console.log(asset.fileName); // e.g. 'IMG_20260822_101500.jpg'
+    console.log(asset.size);     // bytes
+  });
+}
+```
+
+| Option | Meaning |
+| --- | --- |
+| `mediaTypes` | `'all'` (default), `'photo'` or `'video'` |
+| `selectionLimit` | Max items the user can pick. `0` = unlimited |
+| `initialCamera` | `'back'` (default) or `'front'` |
+| `enableVideo` | Set `false` for a photo-only camera |
+| `enableFilter` | Set `false` to hide the filter tool in the editor |
+
+---
+
+## Customizing icons
+
+All icon customization happens in the **`CUSTOM_ICONS`** block of your `App.tsx`. Nothing else to
+edit, no icon library to install.
+
+### Replace a single icon
+
+```tsx
+const CUSTOM_ICONS: CameraIconsConfig = {
+  send: require('./assets/my-send.png'),
+};
+```
+
+### Replace multiple icons
+
+```tsx
+const CUSTOM_ICONS: CameraIconsConfig = {
+  send: require('./assets/my-send.png'),
+  close: require('./assets/my-close.png'),
+  flashOn: require('./assets/flash-on.png'),
+  flashOff: require('./assets/flash-off.png'),
+  delete: { tintColor: '#EF4444' },
+  crop: { resourceName: 'my_crop_icon' },
+};
+```
+
+Every key you leave out keeps the plugin's default icon, so you can replace one icon or all of them.
+
+### The five ways to set an icon
+
+| You write | What happens | Works on |
+| --- | --- | --- |
+| `require('./icon.png')` | Your image is drawn instead | React Native UI |
+| `MyIconComponent` | Your React component is drawn instead | React Native UI |
+| `{ tintColor: '#25D366' }` | The built-in icon is recoloured | Everywhere |
+| `{ resourceName: 'my_icon' }` | Your Android drawable is drawn instead | Native camera screen |
+| `{ svg: '<svg …>…</svg>' }` | Your inline SVG markup is drawn instead | Everywhere |
+| `{ size: 28 }` | The icon is drawn at this size in dp | React Native UI |
+
+You can combine them for one key:
+
+```tsx
+close: { component: MyClose, resourceName: 'my_close', tintColor: '#FFFFFF' },
+```
+
+### Replace an icon with inline SVG
+
+`svg` is the one artwork option that reaches **both** surfaces from a single string — no
+`require()`, no drawable file, no `react-native-svg`. The plugin ships its own tiny SVG renderer
+(React Native draws the markup through a bundled native view; the native camera/editor screen draws
+it directly), so the same markup shows up everywhere the icon is used:
+
+```tsx
+const CUSTOM_ICONS: CameraIconsConfig = {
+  send: {
+    svg: `<svg viewBox="0 0 24 24"><path d="M2 21l21-9L2 3v7l15 2-15 2z" fill="currentColor"/></svg>`,
+  },
+  // Give it a fixed colour, or leave it to follow the icon's own tint:
+  close: { svg: '<svg viewBox="0 0 24 24"><path d="M6 6l12 12M18 6L6 18"/></svg>', tintColor: '#FFFFFF' },
+};
+```
+
+**Supported subset.** The bundled renderer understands a practical, self-contained slice of SVG:
+the `<svg>` root plus `path`, `rect`, `circle`, `ellipse`, `line`, `polyline` and `polygon`, with
+`fill`, `stroke`, `stroke-width`, `opacity` and `transform` (`translate` / `scale` / `rotate`).
+It does **not** run scripts, load external images/fonts, or fetch anything — keep the markup inline
+and under 256 KB.
+
+**Colour.** Use `fill="currentColor"` (or `stroke="currentColor"`) for parts that should follow the
+icon's tint: `tintColor` — or, on React Native, the surrounding `color` — fills in for
+`currentColor`, while any explicit colour in the markup is left untouched. With no tint, an SVG
+keeps its own colours instead of being flattened to one tone.
+
+**Safe fallback.** If the markup is empty, malformed, or uses something the renderer can't draw —
+or on a platform without the native half (iOS / web) — the icon silently falls back to the
+plugin's built-in default rather than showing a blank box.
+
+> **Two surfaces, one key.** The plugin draws icons in two places: your React Native screens, and
+> the native Android camera Activity. A native Android screen can't render a React component or a
+> JS `require()`, so to change its artwork with an image you drop a file into
+> `android/app/src/main/res/drawable/` and name it with `resourceName`. `tintColor` and `svg` need
+> no extra files and reach **both** surfaces. The **Where** column in the table below tells you
+> which surfaces a key reaches.
+
+### Changing icons at runtime
+
+Instead of (or after) `configureCameraPlugin`, you can swap icons at any time:
+
+```tsx
+import { setCameraIcons, resetCameraIcons } from 'react-native-ensys-camera-x';
+
+setCameraIcons({ send: require('./assets/my-send.png') }); // merges with what's set
+resetCameraIcons();                                        // back to all defaults
+```
+
+---
+
+## Icon keys
+
+Every key below goes in `CUSTOM_ICONS`. **Where** tells you which surfaces the key affects:
+**App** = the React Native screens (the media library screen, plus any screen of your own that uses
+`RenderIcon`), **Camera** = the native camera/editor screen, **Both** = both.
+
+### Common controls
+
+| Key | Used for | Where |
+| --- | --- | --- |
+| `close` | Close / dismiss a screen, sheet or overlay | Both |
+| `back` | Back arrow in headers | Both |
+| `done` | Confirm / apply the current step (checkmark) | Both |
+| `cancel` | Cancel an action without applying it | App |
+| `check` | Generic checkmark on list and option rows | App |
+| `selectionCheck` | Checkmark badge on a selected gallery thumbnail | Camera |
+
+### Camera screen
+
+| Key | Used for | Where |
+| --- | --- | --- |
+| `camera` | Generic camera icon (buttons that open the camera) | App |
+| `photo` | Still photo / image media | App |
+| `video` | Video clip media | App |
+| `photoMode` | The "Photo" mode tab | Both |
+| `videoMode` | The "Video" mode tab | Both |
+| `flipCamera` | Switch between front and back camera | Both |
+| `flashOn` | Flash forced on | Both |
+| `flashOff` | Flash off | Both |
+| `flashAuto` | Flash in automatic mode | Both |
+| `gallery` | Gallery / recent media (bottom-left thumbnail) | Both |
+| `record` | Start recording (record dot) | App |
+| `mic` | Microphone — audio recording entry points | App |
+| `lock` | Locked state — hands-free recording engaged | Both |
+| `lockOpen` | The slide-to-lock rail shown while holding to record | Both |
+
+### Editor tools
+
+| Key | Used for | Where |
+| --- | --- | --- |
+| `crop` | Crop tool | Both |
+| `rotate` | Rotate the image 90° | Both |
+| `aspectRatio` | Aspect-ratio picker inside the crop tool | Camera |
+| `filter` | Colour filter strip | Both |
+| `sticker` | Add-sticker tool | Both |
+| `emoji` | Add-emoji tool | Both |
+| `gif` | Add-GIF tool | Camera |
+| `text` | Add-text tool | Both |
+| `textBackground` | Cycle the text background style while typing | Camera |
+| `textAlignLeft` | Text aligned left | Camera |
+| `textAlignCenter` | Text aligned centre | Camera |
+| `textAlignRight` | Text aligned right | Camera |
+| `draw` | Freehand drawing tool | App |
+| `marker` | Marker / pen tool | Camera |
+| `brushThin` | Thin brush width | Camera |
+| `brushMedium` | Medium brush width | Camera |
+| `brushThick` | Thick brush width | Camera |
+| `clearDrawing` | Erase every drawing stroke | Camera |
+| `undo` | Undo the last edit | Both |
+| `redo` | Redo the last undone edit | Both |
+| `overlayClose` | The X that deletes a selected sticker / emoji / GIF / text | Camera |
+| `overlayResize` | The corner handle that resizes a selected overlay | Camera |
+
+### Media actions & playback
+
+| Key | Used for | Where |
+| --- | --- | --- |
+| `play` | Play video or audio | Both |
+| `pause` | Pause playback or recording | Both |
+| `stop` | Stop playback or recording | App |
+| `volumeOn` | Sound on — video audio is kept | Both |
+| `volumeOff` | Sound off — video is muted | Both |
+| `mute` | Muted indicator on a media tile | App |
+| `trim` | Trim a video clip | Both |
+| `cover` | Pick a video's cover frame | Both |
+| `compress` | Compress an image or video | App |
+| `export` | Export in another file format | App |
+| `send` | Send / confirm the selected media | Both |
+| `download` | Save media to the device | Both |
+| `share` | Share media with another app | Both |
+| `delete` | Delete / remove media | Both |
+| `trash` | Dustbin when dragging an overlay away, and bulk-delete bars | App |
+| `more` | Generic overflow / "more" affordance | App |
+| `moreOptions` | The ⋮ overflow button in the preview header | Camera |
+| `upload` | Upload media to a server | App |
+| `uploadStatus` | Status-bar icon of the upload notification (monochrome vector only) | Camera |
+
+### Documents & audio
+
+| Key | Used for | Where |
+| --- | --- | --- |
+| `document` | Document file (PDF, DOCX, …) | Both |
+| `audio` | Audio file | Both |
+| `browseAudio` | Browse the device for an audio file | App |
+| `imageVideo` | Combined image-or-video picker entry point | App |
+
+### Indicators
+
+| Key | Used for | Where |
+| --- | --- | --- |
+| `chevronUp` | Upward chevron — swipe-up hints, expanding panels | Both |
+| `chevronDown` | Downward chevron — collapsing the colour palette | Camera |
+| `chevronRight` | Forward chevron on navigable rows | App |
+| `warning` | Warning / error state | App |
+| `plus` | Add / expand (the floating action button) | App |
+| `minus` | Remove / collapse | App |
+
+---
+
+## Icons by screen
+
+The tables above group icons by feature. This section groups the **same keys** by the screen they
+actually appear on, so you can see at a glance which icons your users meet on the React Native side
+and which live inside the native camera and editor.
+
+Your **React Native screens** draw the keys under *React Native screens* **and** *Both screens*. The
+**native camera / editor** draws the keys under *Native camera screen* **and** *Both screens*.
+
+### React Native screens
+
+The media library grid, the full-screen viewer, the record-audio screen and the expandable "+" menu.
+
+| Key | Used for |
+| --- | --- |
+| `camera` | Buttons that open the camera |
+| `photo` | Still photo / image media |
+| `video` | Video clip media |
+| `record` | Start recording (record dot) |
+| `mic` | Microphone — audio recording entry points |
+| `draw` | Freehand drawing tool |
+| `stop` | Stop playback or recording |
+| `mute` | Muted indicator on a media tile |
+| `compress` | Compress an image or video |
+| `export` | Export in another file format |
+| `trash` | Dustbin when dragging an overlay away, and bulk-delete bars |
+| `more` | Generic overflow / "more" affordance |
+| `upload` | Upload media to a server |
+| `browseAudio` | Browse the device for an audio file |
+| `imageVideo` | Combined image-or-video picker entry point |
+| `chevronRight` | Forward chevron on navigable rows |
+| `warning` | Warning / error state |
+| `plus` | Add / expand affordance |
+| `minus` | Remove / collapse |
+| `plusClose` | Animated FAB plus-to-close morph |
+| `circularSeek` | Video player -10s / +10s seek rings |
+| `viewDetails` | View Details metadata button |
+| `cancel` | Cancel an action without applying it |
+| `check` | Generic checkmark on list and option rows |
+
+### Native camera screen
+
+The native camera Activity and the native photo / video editor.
+
+| Key | Used for |
+| --- | --- |
+| `selectionCheck` | Checkmark badge on a selected gallery thumbnail |
+| `aspectRatio` | Aspect-ratio picker inside the crop tool |
+| `gif` | Add-GIF tool |
+| `textBackground` | Cycle the text background style while typing |
+| `textAlignLeft` | Text aligned left |
+| `textAlignCenter` | Text aligned centre |
+| `textAlignRight` | Text aligned right |
+| `marker` | Marker / pen tool |
+| `brushThin` | Thin brush width |
+| `brushMedium` | Medium brush width |
+| `brushThick` | Thick brush width |
+| `clearDrawing` | Erase every drawing stroke |
+| `overlayClose` | The X that deletes a selected sticker / emoji / GIF / text |
+| `overlayResize` | The corner handle that resizes a selected overlay |
+| `moreOptions` | The ⋮ overflow button in the preview header |
+| `uploadStatus` | Status-bar icon of the upload notification (monochrome vector only) |
+| `chevronDown` | Downward chevron — collapsing the colour palette |
+
+### Both screens
+
+These render on the React Native screens **and** inside the native camera / editor.
+
+| Key | Used for |
+| --- | --- |
+| `close` | Close / dismiss a screen, sheet or overlay |
+| `back` | Back arrow in headers |
+| `done` | Confirm / apply the current step (checkmark) |
+| `photoMode` | The "Photo" mode tab |
+| `videoMode` | The "Video" mode tab |
+| `flipCamera` | Switch between front and back camera |
+| `flashOn` | Flash forced on |
+| `flashOff` | Flash off |
+| `flashAuto` | Flash in automatic mode |
+| `gallery` | Gallery / recent media (bottom-left thumbnail) |
+| `lock` | Locked state — hands-free recording engaged |
+| `lockOpen` | The slide-to-lock rail shown while holding to record |
+| `crop` | Crop tool |
+| `rotate` | Rotate the image 90° |
+| `filter` | Colour filter strip |
+| `sticker` | Add-sticker tool |
+| `emoji` | Add-emoji tool |
+| `text` | Add-text tool |
+| `undo` | Undo the last edit |
+| `redo` | Redo the last undone edit |
+| `play` | Play video or audio |
+| `pause` | Pause playback or recording |
+| `volumeOn` | Sound on — video audio is kept |
+| `volumeOff` | Sound off — video is muted |
+| `trim` | Trim a video clip |
+| `cover` | Pick a video's cover frame |
+| `send` | Send / confirm the selected media |
+| `download` | Save media to the device |
+| `share` | Share media with another app |
+| `delete` | Delete / remove media |
+| `chevronUp` | Upward chevron — swipe-up hints, expanding panels |
+| `document` | Document file (PDF, DOCX, …) |
+| `audio` | Audio file |
+
+> The media-library "+" button's animated `+`↔`×` morph, the video player's ±10-second skip rings,
+> and the "View details" `i` are customizable through `plusClose`, `circularSeek`, and
+> `viewDetails`. Custom components receive the active theme-derived color and the interaction
+> props they need (`progress`, `direction`, and the localized `label`).
+
+---
+
+## Languages
+
+The plugin displays whatever language your app is in. It has no language selector of its own and
+keeps no language state — you pass your app's active language code, and every screen (including the
+native camera and editor) follows it. English is always the fallback, so you only translate what you
+want to translate.
+
+Set it up **once** with a language provider and you never have to tell the plugin about a language
+change again — see [Follow your app's language automatically](#follow-your-apps-language-automatically).
+
+### Set the language
+
+Both of these are shown in the `App.tsx` above:
+
+```tsx
+configureCameraPlugin({
+  translations: MY_LANGUAGES, // one entry per language, keyed by code
+  language: 'en',             // your app's active language
+});
+```
+
+To switch language later — from a settings screen, a language picker, anywhere:
+
+```tsx
+import { setCameraLanguage } from 'react-native-ensys-camera-x';
+
+setCameraLanguage('es'); // takes effect immediately, no restart
+```
+
+If your app keeps its language in React state or context, wrap your screens instead and the plugin
+follows the prop:
+
+```tsx
+import { CameraLocalizationProvider } from 'react-native-ensys-camera-x';
+
+<CameraLocalizationProvider locale={myAppLanguage} bundles={MY_LANGUAGES}>
+  <MyScreens />
+</CameraLocalizationProvider>;
+```
+
+Already using **i18next**, **i18n-js** or similar? Hand over your `t` function and skip the bundles
+entirely:
+
+```tsx
+<CameraLocalizationProvider locale={i18n.language} translate={(key) => t(`camera.${key}`)}>
+```
+
+### Follow your app's language automatically
+
+Instead of calling `setCameraLanguage()` on every switch, hand `language` a small **provider** — an
+object with `get()` and `subscribe()`. Configure it once at startup and from then on the whole plugin
+follows your app on its own: React Native screens re-render, and the new translations, language code
+and text direction are pushed to the native camera and editor live.
+
+```tsx
+import { configureCameraPlugin } from 'react-native-ensys-camera-x';
+import i18n from './i18n';
+
+configureCameraPlugin({
+  translations: MY_LANGUAGES,
+  language: {
+    get: () => i18n.language,
+    subscribe: (onChange) => {
+      i18n.on('languageChanged', onChange);
+      return () => i18n.off('languageChanged', onChange); // returned so it can be released
+    },
+  },
+});
+```
+
+That is the entire integration. No `setCameraLanguage()` calls anywhere else in your app.
+
+Any language source works — the provider is just two functions:
+
+```tsx
+// Redux / Zustand / any store
+language: {
+  get: () => store.getState().language,
+  subscribe: (onChange) => store.subscribe(onChange),
+}
+
+// Your own emitter
+language: {
+  get: () => Settings.language,
+  subscribe: (onChange) => {
+    const sub = Settings.events.addListener('language', onChange);
+    return () => sub.remove();
+  },
+}
+```
+
+`subscribe` may return an unsubscribe function, an object with `remove()` or `unsubscribe()`, or
+nothing at all. Your callback may be handed the new code (i18next passes it) or called bare — the
+plugin re-reads `get()` when no code arrives.
+
+You can also bind it on its own, at any time:
+
+```tsx
+import {
+  setCameraLanguageProvider,
+  clearCameraLanguageProvider,
+  syncCameraLanguage,
+} from 'react-native-ensys-camera-x';
+
+setCameraLanguageProvider({ get: () => i18n.language, subscribe: … });
+
+clearCameraLanguageProvider(); // back to manual switching
+syncCameraLanguage();          // force a re-read, if your source can't notify
+```
+
+Notes worth knowing:
+
+- **Your app stays the single source of truth.** The plugin never reads the device locale and keeps
+  no language of its own — it mirrors whatever `get()` reports.
+- **Binding is idempotent.** Passing the same provider object again re-reads it without adding a
+  second listener; passing a different one releases the previous subscription first. Safe to call
+  from a startup path that runs more than once.
+- **`setCameraLanguage()` still works** as a manual fallback while a provider is bound. The next
+  change your provider reports wins, because your app owns the language.
+- **Bundles and the English fallback are untouched.** Register `translations` once and the provider
+  just picks the right bundle; missing keys still fall back to `fallbackLanguage`, then to English.
+
+### Language codes
+
+Any standard code works — `en`, `es`, `fr`, `de`, `it`, `pt`, `pt-BR`, `ru`, `pl`, `ro`, `da`, `sv`,
+`uk`, `tr`, `vi`, `hi`, `bn`, `ja`, `ko`, `fa`, `ar`, `zh-Hans`, `zh-Hant`, … There is no list of
+supported languages inside the plugin: it reads the code you give it, so adding a language to your
+app never requires a plugin change.
+
+Regional and script variants fall back sensibly, so one bundle can cover several codes:
+
+| You provide | Covers |
+| --- | --- |
+| `pt` | `pt`, `pt-BR`, `pt-PT` |
+| `zh-Hans` | `zh-Hans`, `zh-CN`, `zh-SG` |
+| `zh-Hant` | `zh-Hant`, `zh-TW`, `zh-HK` |
+| `fa` | `fa`, `fa-AF`, `prs` (Dari) |
+| *(nothing)* | English |
+
+### Right-to-left languages
+
+Arabic, Persian/Farsi, Hebrew, Urdu and other RTL languages are detected from the language code —
+you don't maintain a list or pass a flag. Setting `language: 'ar'` mirrors the layout, flips text
+alignment, and repositions toolbars and controls across both the React Native screens and the native
+camera.
+
+To force a direction anyway, pass `isRtl` and it wins:
+
+```tsx
+<CameraLocalizationProvider locale="ku" bundles={MY_LANGUAGES} isRtl={false}>
+```
+
+### Translating your own screens
+
+The same strings are available to your components:
+
+```tsx
+import { useCameraLocalization } from 'react-native-ensys-camera-x';
+
+const { t, locale, isRtl, textAlign } = useCameraLocalization();
+
+<Text style={{ textAlign }}>{t('gallery')}</Text>;
+```
+
+### Full list of text keys
+
+Every button, label, dialog, error message, editor and camera control, video control, empty state,
+permission prompt and metadata format has a key. The complete list — over 400 keys, each with its
+English default — is in **[MULTILINGUAL_INTEGRATION.md](./MULTILINGUAL_INTEGRATION.md)**, along with
+ready-made integration patterns. You can also read the defaults at runtime:
+
+```tsx
+import { defaultTranslations } from 'react-native-ensys-camera-x';
+
+console.log(Object.keys(defaultTranslations)); // every available key
+```
+
+A few keys carry placeholders (`{0}`, `{1}`) that are filled in at runtime — keep them in your
+translation: `selectedCount: '{0} seleccionados'`.
+
+---
+
+## Other pickers (optional)
+
+Same `{ cancelled, assets }` result as `openCameraPicker`:
+
+```tsx
+import {
+  openDocumentPicker,
+  openAudioPicker,
+  openImageVideoPicker,
+  openGalleryEditor,
+} from 'react-native-ensys-camera-x';
+
+await openDocumentPicker();    // PDFs, Word, Excel, …
+await openAudioPicker();       // audio files
+await openImageVideoPicker();  // system photo/video picker
+await openGalleryEditor();     // pick from the gallery, straight into the editor
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+| --- | --- |
+| `openCameraPicker is not a function` | Stop Metro and rebuild: `npm run android`. Native modules need a rebuild, not a reload. |
+| `'react-native-sqlcipher' is not available` | The media library screen needs it: `npm install react-native-sqlcipher`, then rebuild. |
+| Build fails with *More than one file was found with OS independent path `lib/…/libcrypto.so`* | Two libraries ship the same native library. Add the `packagingOptions` block below to `android/app/build.gradle`. |
+| A custom icon doesn't show on the camera screen | The native screen can't draw a `require()` or a React component. Use `resourceName` (a drawable in `android/app/src/main/res/drawable/`), or an inline `svg` — both reach the native screen. |
+| Your PNG icon looks flat / single-coloured | Remove `tintColor` for that key — it recolours the whole image. |
+| Your inline `svg` shows the default icon instead | The markup is empty, over 256 KB, or uses something outside the supported subset (gradients, `<text>`, `<image>`, filters, CSS, arc path commands). Simplify it to `path`/`rect`/`circle`/`ellipse`/`line`/`polyline`/`polygon`, or check it renders on the native screen — it falls back to the built-in icon on iOS / web. |
+| The camera asks for permission again | Android grants "Only this time" permissions for one session. Choose "While using the app" to keep it. |
+| A screen is still in English | That key isn't in the bundle for the active language. Check the code you passed matches a key in `translations`, and that the key names match the list in [MULTILINGUAL_INTEGRATION.md](./MULTILINGUAL_INTEGRATION.md). |
+| Build fails on SDK version | Your app needs `minSdkVersion 24` or higher in `android/build.gradle`. |
+
+The duplicate-native-library fix, inside the existing `android { … }` block of
+`android/app/build.gradle`:
+
+```gradle
+android {
+    // …
+
+    packagingOptions {
+        pickFirst "**/libc++_shared.so"
+        pickFirst "**/libcrypto.so"
+        pickFirst "**/libssl.so"
+    }
+}
+```
+
+---
+
+## License
+
+MIT © Asif Ali