useUpdateStream

Hook for updating an existing Stream (opens in a new tab).

Usage

React

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

The following example shows how an stream can be updated to enable recording and require a JWT for playback (see the Access Control example for more details).

const streamId = 'abcff74a-bb19-45af-8e63-b961efa1899e';
 
function SomeComponent() {
  const { data: stream } = useStream({
    streamId,
    refetchInterval: 10000,
  });
  const {
    mutate: updateStream,
    status,
    error,
  } = useUpdateStream({
    streamId,
    record: true,
    playbackPolicy: {
      type: 'jwt',
    },
  });
 
  return (
    <div>
      <button
        disabled={status === 'loading' || stream.record || !updateStream}
        onClick={() => {
          updateStream?.();
        }}
      >
        Enable Recording
      </button>
      {stream && (
        <>
          <div>Stream Name: {stream?.name}</div>
          <div>Recording?: {String(Boolean(stream.record))}</div>
        </>
      )}
      {error && <div>{error.message}</div>}
    </div>
  );
}

Return Value

The return value is partially based on React Query (opens in a new tab), with some return types aggregated for simplicity.

{
  data?: Stream,
  error?: Error,
  isError: boolean,
  isIdle: boolean,
  isLoading: boolean,
  isSuccess: boolean,
  status: 'idle' | 'loading' | 'success' | 'error',
  mutate: () => void,
  mutateAsync: () => Promise<Stream>,
  variables?: UpdateStreamArgs
}

Configuration

streamId

The stream ID to update - required.

function SomeComponent() {
  const { mutate: createStream } = useUpdateStream({
    streamId,
    record: true,
  });
}

suspend

Whether to immediately block ingest and playback of the stream.

record

Whether to create recordings of the stream sessions. Defaults to false.

multistream

The configuration for multistreaming (AKA "restream" or "simulcast") - allows configuration of targets where this stream should be simultaneously streamed to.

The multistream targets can be either a full MultistreamTarget like on create, or a MultistreamTargetRef. The Ref object comes directly from the existing Stream object, in case multistream has already been configured for the given stream. It contains a vanity ID instead of the full Spec since the ingest URL contains user secrets like the stream key.

type MultistreamTarget = {
  /**
   * Name of transcoding profile that should be sent. Use "source" for pushing
   * source stream data
   */
  profile: string;
  /**
   * If true, the stream audio will be muted and only silent video will be
   * pushed to the target.
   */
  videoOnly?: boolean;
  /**
   * Unique ID of this multistream target. Used to dedup targets on update.
   */
  id?: string;
  /**
   * Inline spec for the multistream target object. Underlying target resource
   * will be automatically created.
   */
  spec?: {
    /** Name for the multistream target. Defaults to the URL hostname */
    name?: string;
    /** Livepeer-compatible multistream target URL (RTMP(s) or SRT) */
    url: string;
  };
};

playbackPolicy

Configuration for stream playback access-control policy. Defaults to public.

type PlaybackPolicy = {
  /**
   * The type of playback policy to apply. `jwt` requires a signed JWT for
   * playback. `webhook` requires that a webhook is configured and passed during the
   * creation of the asset. `public` indicates no
   * access control will be applied (anyone with the `playbackId` can
   * view without a JWT or webhook).
   */
  type: 'webhook' | 'jwt' | 'public';
};
 
type WebhookPlaybackPolicy<TContext extends object> = PlaybackPolicy & {
  type: 'webhook';
  /** The ID of the webhook which has already been created. */
  webhookId: string;
  /** The context which is passed to the webhook when it is called on playback. */
  webhookContext: TContext;
};

For more details on the playback policy, see the Access Control example.

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.

function SomeComponent() {
  const { mutate: updateStream } = useUpdateStream({
    streamId,
    record: true,
    mutationConfig: { retry: 3 },
  });
}

useCreateStream usePlaybackInfo