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,
              storage: {
                ipfs: true,
                metadata: {
                  name: 'interesting video',
                  description: 'a great description of the 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,
        creatorId: '0xabcd000000000000000000000000000000001234',
        storage: {
          ipfs: true,
          metadata: {
            name: 'interesting video',
            description: 'a great description of the 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;
  /** The storage configs for the new asset (e.g. IPFS) */
  storage?: Storage;
  /**
   * Sets the playback policy for the asset created.
   */
  playbackPolicy?: PlaybackPolicy;
  /**
   * Sets the creator ID for the asset that is created.
   * This should be an wallet's public address.
   */
  creatorId?: CreateAssetCreatorId;
};
 
/** 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;
  /** The storage configs for the new asset (e.g. IPFS) */
  storage?: Storage;
  /**
   * Sets the playback policy for the asset created.
   */
  playbackPolicy?: PlaybackPolicy;
  /**
   * Sets the creator ID for the asset that is created.
   * This should be an wallet's public address.
   */
  creatorId?: CreateAssetCreatorId;
};
 
/** Source(s) to upload - can be a file or URL source */
type Sources = CreateAssetSourceFile[] | CreateAssetSourceUrl[];

We are planning on adding further features to the creator ID such as provable claims. Reach out to us on Discord (opens in a new tab) if you're interested!

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.

storage

The storage configs can be applied on asset creation. See useUpdateAsset for more details on these configs. If the storage parameter is omitted, the asset will not be stored in decentralized storage.

💡

If you would like to use Arweave as storage, we recommend you upload to Arweave first and then import the video.

type Storage = {
  /**
   * If the asset should be stored on IPFS.
   */
  ipfs?: boolean;
  /**
   * Metadata exported to the storage provider. This will be deep merged with the default
   * metadata from the livepeer provider. This should ideally be EIP-721/EIP-1155 compatible.
   *
   * @see {@link https://eips.ethereum.org/EIPS/eip-721}
   */
  metadata?:
    | Partial<Metadata> & {
        [k: string]: unknown;
      };
  /**
   * The metadata template to use. `player` will embed the Livepeer Player's IPFS CID while `file`
   * will reference only the immutable media files.
   */
  metadataTemplate?: 'player' | 'file';
};

The metadata can be overridden when the Asset and its metadata are exported to IPFS - we provide some helper types for metadata best practices based on ERC-721 and ERC-1155:

type Metadata = {
  /** Name of the Asset */
  name?: string;
  /** Description of the Asset */
  description?: string;
  /** Image URL for the Asset */
  image?: string;
  /** Properties of the Asset */
  properties?: {
    [k: string]: unknown;
  };
  /**
   * Background color for the Asset (OpenSea Standard)
   *
   * @see {@link https://docs.opensea.io/docs/metadata-standards}
   */
  background_color?: string;
  /**
   * Attributes for the Asset (OpenSea Standard)
   *
   * @see {@link https://docs.opensea.io/docs/metadata-standards}
   */
  attributes?: {
    [k: string]: unknown;
  };
};

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