useCreateAsset
Hook for creating a new Asset (opens in a new tab).
Usage
import { useCreateAsset } from '@livepeer/react';
The asset ID should only be passed to users who are allowed to modify the
asset. Ensure viewers are only provided with the playbackId
, which is a
limited identifier that provides only the ability to stream media using the
Player
.
The following example shows how an asset can be created with the mutate
function. The variables are passed into the
useCreateAsset
hook, and createAsset
return type is defined when the variables are truthy.
function SomeComponent() {
const [video, setVideo] = useState<File | undefined>(undefined);
const {
mutate: createAsset,
data: assets,
status,
progress,
error,
} = useCreateAsset(
// we use a `const` assertion here to provide better Typescript types
// for the returned data
video
? {
sources: [{ name: video.name, file: video }] as const,
}
: null,
);
return (
<div>
<input
type="file"
multiple={false}
accept="video/*"
onChange={(e) => {
if (e.target.files) {
setVideo(e.target.files[0]);
}
}}
/>
<button
disabled={status === 'loading' || !createAsset}
onClick={() => {
createAsset?.();
}}
>
Create Asset
</button>
{assets?.map((asset) => (
<div key={asset.id}>
<div>
<div>Asset Name: {asset?.name}</div>
<div>Playback URL: {asset?.playbackUrl}</div>
<div>IPFS CID: {asset?.storage?.ipfs?.cid ?? 'None'}</div>
</div>
</div>
))}
{error && <div>{error.message}</div>}
</div>
);
}
Mutation
Return Value
The return value is partially based on React Query (opens in a new tab), with some return types aggregated for simplicity.
The value progress
is an array of progress values which contains the upload progress from
tus (opens in a new tab), as well as the processing progress of the asset from the provider. These values are polled consistently
until the asset succeeds or fails to be processed by the provider.
{
data?: Asset[],
progress?: CreateAssetProgress,
error?: Error,
isError: boolean,
isIdle: boolean,
isLoading: boolean,
isSuccess: boolean,
status: 'idle' | 'loading' | 'success' | 'error',
mutate: () => void,
mutateAsync: () => Promise<Asset[]>,
variables?: CreateAssetArgs
}
Configuration
sources
The sources
used for the asset creation can be an array of either a URL or a local File/ReadStream/object with a uri
string.
It is highly recommended to use
const assertions (opens in a new tab)
to infer types properly from the sources
parameter - please see below for an example.
import { useCreateAsset } from '@livepeer/react';
function SomeComponent() {
const { mutate: createAsset, status } = useCreateAsset({
sources: [{ name: video.name, file: video }] as const,
});
}
The useCreateAsset
hook uses tus (opens in a new tab) for
resumable uploads and checks for existing uploads by default, before starting
a new upload. It also automatically polls the livepeer provider's API to
update status
until the import job is complete.
The sources
type can be either a URL or a File/ReadStream:
type CreateAssetSourceUrl = {
/** Name for the new asset */
name: string;
/** External URL to be imported */
url: string;
};
/** React Native file type */
type NativeFile = File & {
uri: string;
};
type CreateAssetSourceFile = {
/** Name for the new asset */
name: string;
/** Content to be uploaded or streamed */
file: File | ReadStream | NativeFile;
};
/** Source(s) to upload - can be a file or URL source */
type Sources = CreateAssetSourceFile[] | CreateAssetSourceUrl[];
If CreateAssetSourceFile
is passed in the array, the useCreateAsset
hook uses tus (opens in a new tab) for resumable uploads and checks for existing uploads by default, before starting a
new upload.
If CreateAssetSourceUrl
is passed in the array, the hook will make a request to the background to start an import. This can also
be an IPFS URL (ipfs://<CID>
) or Arweave URL (ar://<HASH>
). Either a URL or file must be provided.
noWait
The noWait
config option skips the polling mechanism which waits for the Asset upload to succeed or fail. It will immediately return after the file upload is complete,
or in the case of a URL upload, it will return after the URL is POST
ed to the backend.
import { useCreateAsset } from '@livepeer/react';
function SomeComponent() {
const { mutate: createAsset } = useCreateAsset({
sources: [{ name: video.name, file: video }] as const,
noWait,
});
}
mutationConfig
The mutationConfig
parameter allows for any React Query (opens in a new tab) useMutation
options, such as
cacheTime
or retry
. These override any configs passed by default by the internal hook.
import { useCreateAsset } from '@livepeer/react';
function SomeComponent() {
const { mutate: createAsset } = useCreateAsset({
sources: [{ name: video.name, file: video }] as const,
mutationConfig: { retry: 5 },
});
}