useCreateAsset

Hook for creating a new Asset (opens in a new tab).

Usage

React

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.

React

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 POSTed 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 },
  });
}

useAsset useAssetMetrics