Live photo
@symbiote-native/live-photo wraps
expo-live-photo, so every
SymbioteNative adapter can show a Live Photo, not just React. On Android the view renders nothing.
Installation
Section titled “Installation”npm install @symbiote-native/live-photoScaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --live-photo
(or add --live-photo in an existing app) installs and wires this for you.
The photo and the video must come from one unaltered live photo file, the pairing lives in their metadata. Keep the handle of the view to start and stop playback.
import { useRef } from 'react';import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/react';
const handle = useRef<ILivePhotoViewHandle>(null);
<LivePhotoView ref={handle} style={{ width: 300, height: 400 }} source={{ photoUri, pairedVideoUri }} onLoadError={error => console.warn(error.message)}/>;<button title="Play" onPress={() => handle.current?.startPlayback('hint')} />;<script setup lang="ts">import { ref } from 'vue';import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/vue';
const handle = ref<ILivePhotoViewHandle | null>(null);</script>
<template> <LivePhotoView ref="handle" :style="{ width: 300, height: 400 }" :source="{ photoUri, pairedVideoUri }" @loadError="error => console.warn(error.message)" /> <button title="Play" @press="handle?.startPlayback('hint')" /></template>import { Component } from '@angular/core';import { SYMBIOTE_ELEMENTS } from '@symbiote-native/angular';import { LivePhotoView } from '@symbiote-native/live-photo/angular';
@Component({ standalone: true, imports: [LivePhotoView, SYMBIOTE_ELEMENTS], template: ` <LivePhotoView #view [style]="{ width: 300, height: 400 }" [source]="{ photoUri, pairedVideoUri }" [onLoadError]="onLoadError" /> <button title="Play" (press)="view.startPlayback('hint')" /> `,})export class LivePhotoCard { readonly photoUri = '...'; readonly pairedVideoUri = '...'; readonly onLoadError = (error: { message: string }): void => console.warn(error.message);}<script lang="ts"> import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/svelte';
let handle = $state<ILivePhotoViewHandle | undefined>();</script>
<LivePhotoView bind:this={handle} style={{ width: 300, height: 400 }} source={{ photoUri, pairedVideoUri }} onLoadError={error => console.warn(error.message)}/><button title="Play" onPress={() => handle?.startPlayback('hint')} />import { createSignal } from 'solid-js';import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/solid';
const [handle, setHandle] = createSignal<ILivePhotoViewHandle>();
<LivePhotoView ref={setHandle} style={{ width: 300, height: 400 }} source={{ photoUri, pairedVideoUri }} onLoadError={error => console.warn(error.message)}/>;<button title="Play" onPress={() => handle()?.startPlayback('hint')} />;Reaching the playback functions
Section titled “Reaching the playback functions”| Adapter | How |
|---|---|
| React | ref gets an ILivePhotoViewHandle |
| Solid | ref={handle => ...} gets the handle |
| Vue | a template ref, startPlayback/stopPlayback are exposed |
| Svelte | bind:this, the component exports both functions |
| Angular | @ViewChild(LivePhotoView), both are methods |
| Prop | Description |
|---|---|
source |
{ photoUri, pairedVideoUri } |
isMuted |
true by default |
contentFit |
contain (default) or cover |
useDefaultGestureRecognizer |
Press and hold plays, true by default |
onLoadStart |
Loading began |
onPreviewPhotoLoad |
The preview photo is loaded |
onLoadComplete |
Ready to play |
onLoadError |
Gets { message } |
onPlaybackStart / onPlaybackStop |
Playback state changed |
Plus style, testID, nativeID, onLayout and the accessibility and responder props every View takes.
- iOS only. Off iOS the view renders nothing, with a warning in development, and the handle
throws
UnavailabilityError. CheckPlatform.OSbefore you render it. - A Live Photo is two files. The still photo and the paired video, and they must stay a pair: the pairing lives in their metadata, so editing or recompressing either one breaks it.
- Playback style.
startPlayback()plays the full clip,startPlayback('hint')plays the short preview you see when you press a photo in the Photos app. - Muted by default.
isMutedistrue, unmute it when the sound is part of the content. - Press and hold plays while
useDefaultGestureRecognizeristrue. Turn it off and callstartPlaybackyourself if the photo has its own gestures.
Common questions
Section titled “Common questions”Where do I get photoUri and pairedVideoUri? From the picker. With
@symbiote-native/image-picker, ask for
mediaTypes: ['livePhotos'] and read assets[0].uri for the photo and
assets[0].pairedVideoAsset?.uri for the video. A photo stored in iCloud and not on the phone needs
the picker’s shouldDownloadFromNetwork option, or the pair may not arrive.
I cannot find a Live Photo in the Simulator. Live Photos are made by the iPhone camera. The Simulator cannot take one, so test with a real device and a photo that has the Live badge.
onLoadError fires, or the photo shows but never plays. The two files do not belong together.
Pass the two URIs that came out of one pick, not a photo from one place and a video from another,
and do not run either through an editor or an image manipulator first.
Can I get the pair from the media library? The shared-object API of
@symbiote-native/media-library resolves the paired video of a
Live Photo, but resolving the still half as a local file was reported to throw for some assets, and
getAssetInfoAsync crashed on Live Photos on iOS in SDK 56 before a fix. The picker is the safer
way to get a ready pair.
It plays without sound. isMuted defaults to true. Pass isMuted={false}.
How do I start playback from a button? Keep the handle and call startPlayback('full') or
startPlayback('hint'), and stopPlayback() to end it. onPlaybackStart and onPlaybackStop tell
you when the state changes.
Does it work on Android? No, Live Photo is an Apple format. The view renders nothing there.
Sources:
- Expo docs: LivePhoto
- expo/expo#47730 Asset.getLivePhotoPhotoUri for Live Photo playback
- expo/expo#46512 getAssetInfoAsync crashes on Live Photos
- expo/expo#48658 iCloud-offloaded assets in the image picker
How the wrapper works
Section titled “How the wrapper works”expo-live-photo’s JS is hand-ported into this package’s core/. A native Expo view keeps its
functions on its module’s view prototypes and native finds the view by its native tag, so the
engine’s defineExpoViewMethods makes that call and the core createLivePhotoViewHandle(getNode)
wraps it. Each adapter only hands over its host node: React and Vue a function ref in the
descriptor props, Solid the same through spread, Svelte bind:this, Angular the outlet’s root
node. The handle is a ref in React and Solid, expose in Vue, exported functions in Svelte and
methods in Angular.
The package declares only ios.upstreamPackage in native-link.json, since upstream has no
Android folder and no config plugin. The native code is never vendored: expo-modules-autolinking
resolves it from node_modules (see the native setup guide).