Skip to content
We've just launched - check out our docs! đź“—
  • React
  • Asset
  • useCreateAsset

useCreateAsset

Hook for creating a new Asset.

import { useCreateAsset } from '@livepeer/react';

Usage

đź’ˇ

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 App() {
  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, with some return types aggregated for simplicity.

The value progress is an array of progress values which contains the upload progress from tus, 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. It is highly recommended to use const assertions to infer types properly from the sources parameter - please see below for an example.

import { useCreateAsset } from '@livepeer/react';
 
function App() {
  const { mutate: createAsset, status } = useCreateAsset({
    sources: [{ name: video.name, file: video }] as const,
  });
}
đź’ˇ

The useCreateAsset hook uses tus 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;
};
 
type CreateAssetSourceFile = {
  /** Name for the new asset */
  name: string;
  /** Content to be uploaded or streamed */
  file: File | ReadStream;
};
 
/** 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 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 POSTed to the backend.

import { useCreateAsset } from '@livepeer/react';
 
function App() {
  const { mutate: createAsset } = useCreateAsset({
    sources: [{ name: video.name, file: video }] as const,
    noWait,
  });
}

mutationConfig

The mutationConfig parameter allows for any React Query useMutation options, such as cacheTime or retry. These override any configs passed by default by the internal hook.

import { useCreateAsset } from '@livepeer/react';
 
function App() {
  const { mutate: createAsset } = useCreateAsset({
    sources: [{ name: video.name, file: video }] as const,
    mutationConfig: { retry: 5 },
  });
}