Hook for retrieving a
Stream Session
based on a unique identifier.
Usage
import { useStreamSession } from '@livepeer/react';
The following examples assume a stream session was created via streaming to an
existing Stream. If a falsy stream session ID is provided, the query will be
skipped.
function SomeComponent() {
const { data: streamSession } = useStreamSession(streamSession?.id);
}
Return Value
The return value is partially based on
Tanstack Query, with
some return types aggregated for simplicity.
{
data?: StreamSession,
error?: Error,
status: 'idle' | 'loading' | 'success' | 'error',
isError: boolean,
isFetched: boolean,
isFetching: boolean,
isIdle: boolean,
isLoading: boolean,
isRefetching: boolean,
isSuccess: boolean,
refetch: (options: RefetchOptions) => Promise<UseQueryResult>,
}
Configuration
streamSessionId
Stream session identifier. Can also be a string passed as the only parameter.
function SomeComponent() {
const { data: streamSession } = useStreamSession({
streamSessionId,
});
}
UseQueryOptions
The useStreamSession
hook also supports any
Tanstack Query
useQuery
options, such as refetchInterval
or enabled
. These override any
configs passed by default by the internal hook.
function SomeComponent() {
const { data: streamSession } = useStreamSession({
streamSessionId,
refetchInterval: (streamSession) =>
streamSession?.recordingStatus !== "ready" ? 5000 : false,
});
}
SSR
The following section only applies to web-based use-cases - React Native has
no concept of SSR.
Next.js
The useStreamSession
hook also comes with a
Tanstack Query prefetch query,
prefetchStreamSession
, which makes it easy to prefetch data for server-side
rendering.
First, you add a
getStaticProps
function to the page which you want to prefetch data on. The props should match
the useStreamSession
hook to ensure that the correct data is prefetched.
import { prefetchStreamSession, studioProvider } from "@livepeer/react";
export const getStaticProps = async () => {
const dehydratedState = await prefetchStreamSession(
{ streamSessionId },
{ provider: studioProvider({ apiKey: "yourStudioApiKey" }) },
);
return {
props: {
dehydratedState,
},
revalidate: 600,
};
};
We need to update the _app.tsx
to pass the dehydratedState
in pageProps
to
the LivepeerConfig. We also move the livepeerClient
into a useMemo hook so
that a new client is created on each request.
import {
LivepeerConfig,
createReactClient,
studioProvider,
} from "@livepeer/react";
import type { AppProps } from "next/app";
import { useMemo } from "react";
function App({ Component, pageProps }: AppProps<{ dehydratedState: string }>) {
const livepeerClient = useMemo(
() =>
createReactClient({
provider: studioProvider({
apiKey: process.env.NEXT_PUBLIC_STUDIO_API_KEY,
}),
}),
[],
);
return (
<LivepeerConfig
dehydratedState={pageProps?.dehydratedState}
client={livepeerClient}
>
<Component {...pageProps} />
</LivepeerConfig>
);
}
That’s it! You now have data prefetching on the server, which is passed to the
browser and used to hydrate the initial query client.
Other Frameworks
The process is very similar for other frameworks, with the exception that there
is a clearClient
boolean which should be used to ensure that the client cache
is not reused across users.
import { prefetchStreamSession, studioProvider } from "@livepeer/react";
export const handleRequest = async (req, res) => {
const dehydratedState = await prefetchStreamSession(
{
streamSessionId,
clearClient: true,
},
{ provider: studioProvider({ apiKey: "yourStudioApiKey" }) },
);
res.send(`
<html>
<body>
<div id="root">${html}</div>
<script>
window.__REACT_QUERY_STATE__ = ${yourSanitizedDehydratedState};
</script>
</body>
</html>
`);
};