diff --git a/.github/dscout_logo.png b/.github/images/dscout_logo.png similarity index 100% rename from .github/dscout_logo.png rename to .github/images/dscout_logo.png diff --git a/.github/xcode1.png b/.github/images/xcode1.png similarity index 100% rename from .github/xcode1.png rename to .github/images/xcode1.png diff --git a/.github/xcode2.png b/.github/images/xcode2.png similarity index 100% rename from .github/xcode2.png rename to .github/images/xcode2.png diff --git a/.github/xcode3.png b/.github/images/xcode3.png similarity index 100% rename from .github/xcode3.png rename to .github/images/xcode3.png diff --git a/.github/workflows/publish_docs.yaml b/.github/workflows/publish_docs.yaml new file mode 100644 index 00000000..e5645bc1 --- /dev/null +++ b/.github/workflows/publish_docs.yaml @@ -0,0 +1,29 @@ +name: Deploy Docs +on: + push: + tags: + - "v*" + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + # the same as in our docker_membrane repository + node-version: 16 + + - name: Install yarn Dependencies + run: yarn + + - name: Build Docs + run: yarn docs + + - name: Deploy + uses: s0/git-publish-subdir-action@develop + env: + REPO: self + BRANCH: gh-pages + FOLDER: docs + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/README.md b/README.md index 62e726eb..144249e1 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ react-native-membrane-webrtc is a React Native wrapper for [membrane-webrtc-android](https://github.com/membraneframework/membrane-webrtc-android) and [membrane-webrtc-ios](https://github.com/membraneframework/membrane-webrtc-ios). It allows you to quickly and easily create a mobile client app in React Native for Membrane server. +# Documentation +API documentation is available [here](https://docs.membrane.stream/react-native-membrane-webrtc/) + # Installation Firstly install react-native-membrane with `yarn` or `npm` @@ -61,19 +64,19 @@ On iOS installation is a bit more complicated, because you need to setup a scree 2. Open your `.xcworkspace` in Xcode 3. Create new Broadcast Upload Extension. Select File → New → Target... → Broadcast Upload Extension → Next. Choose the name for the new target, select Swift language and deselect "Include UI Extension". - ![New target config](/.github/xcode1.png) + ![New target config](./.github/images/xcode1.png) Press Finish. In the next alert xcode will ask you if you want to activate the new scheme - press Cancel. 4. Configure app group. Go to "Signing & Capabilities" tab, click "+ Capability" button in upper left corner and select "App Groups". - ![App groups config](/.github/xcode2.png) + ![App groups config](./.github/images/xcode2.png) Then in the "App Groups" add a new group or select existing. Usually group name has format `group.`. Verify that both app and extension targets have app group and dev team set correctly. 5. A new folder with app extension should appear on the left with contents like this: - ![App extension files](/.github/xcode3.png) + ![App extension files](./.github/images/xcode3.png) Replace `SampleHandler.swift` with `MembraneBroadcastSampleHandler.swift` and this code: @@ -252,231 +255,6 @@ const { isScreencastOn, toggleScreencast } = useScreencast(); toggleScreencast({screencastMetadata: { displayName: "Annie's desktop" }}); ``` -# API - -## `useMembraneServer()` - -The hook used to manage a connection with membrane server. - -### Returns - -An object with functions to manage membrane server connection: - -### `connect(url: string, roomName: string, connectionOptions: ConnectionOptions)` - -Connects to a room. - -Arguments: - -- `url: string` -- server url -- `roomName: string` -- room name -- `connectionOptions` - - `quality: VideoQuality` -- resolution + aspect ratio of local video track, one of: `QVGA_169`, `VGA_169`, `QHD_169`, `HD_169`, `FHD_169`, `QVGA_43`, `VGA_43`, `QHD_43`, `HD_43`, `FHD_43`. Note that quality might be worse than specified due to device capabilities, internet connection etc. Default: `VGA_169`. - - `flipVideo: boolean` -- whether to flip the dimensions of the video, that is whether to film in vertical orientation. Default: `true` - - `userMetadata: Metadata` -- a map `string -> string` containing user metadata to be sent to the server. Use it to send for example user display name or other options. - - `videoTrackMetadata: Metadata` -- a map `string -> string` containing video track metadata to be sent to the server. - - `audioTrackMetadata: Metadata` -- a map `string -> string` containing audio track metadata to be sent to the server. - - `connectionParams: SocketConnectionParams` -- a map `string -> string` containing connection params passed to the socket. - - `simulcastConfig: SimulcastConfig` - [SimulcastConfig](#SimulcastConfig) of a video track. By default simulcast is disabled. - - `maxBandwidth: TrackBandwidthLimit` - [bandwidth limit](#TrackBandwidthLimit) of a video track. By default there is no bandwidth limit. - -Returns: -A promise that resolves on success or rejects in case of an error. - -### `joinRoom()` - -Call this after successfully connecting with the server to join the room. Other participants' tracks will be sent and the user will be visible to other room participants. - -Returns: -A promise that resolves on success or rejects in case of an error. - -### `disconnect()` - -Call this to gracefully disconnect from the server. After that you can connect again. - -Returns: -A promise that resolves on success or rejects in case of an error. - -### `error` - -This variable will contain an error when user failed to connect, join or during a conversation (for example internet connection is lost). - -## `useRoomParticipants()` - -This hook provides live updates of room participants. - -### Returns - -An array of room participants. - -`type Participant` - -- `id: string` -- id used to identify a participant -- `type: ParticipantType` -- used to indicate participant type. Possible values: `Remote`, `Local`, `LocalScreencasting`. When user is screencasting, a new fake participant is created. -- `metadata: Metadata` -- a map string -> string containing participant metadata from the server - -## `useCameraState()` - -This hook can toggle camera on/off and provides current camera state. - -### Returns - -An object containig: - -- `isCameraOn: boolean` -- `toggleCamera: () => Promise` - -## `useMicrophoneState()` - -This hook can toggle microphone on/off and provides current microphone state. - -### Returns - -An object containig: - -- `isMicrophoneOn: boolean` -- `toggleMicrophone: () => Promise` - -## `flipCamera()` - -Function that's toggles between front and back camera. By default the front camera is used. - -### Returns - -A promise that resolves when camera is toggled. - -## `useScreencast()` - -This hook can toggle screen sharing on/off and provides current screencast state. - -### Returns - -An object containing: - -- `isScreencastOn: boolean` -- `toggleScreencast(screencastOptions: ScreencastOptions)` - toggles the screencast on/off. Arguments: - - - `screencastOptions: ScreencastOptions` - - `quality: ScreencastQuality` - resolution + fps of screencast track, one of: `VGA`, `HD5`, `HD15`, `FHD15`, `FHD30`. Note that quality might be worse than specified due to device capabilities, internet connection etc. Default: `HD15`. - - `screencastMetadata: Metadata` - a map `string -> string` containing screencast track metadata to be sent to the server. - - `simulcastConfig: SimulcastConfig` - [SimulcastConfig](#simulcastconfig) of a screencast track. By default simulcast is disabled. - - `maxBandwidth: TrackBandwidthLimit` - [bandwidth limit](#trackbandwidthlimit) of a screencast track. By default there is no bandwidth limit. - -- `updateScreencastTrackMetadata(metatada: Metadata)` - a function that updates screencast track metadata on the server. Arguments: - - `metatada: Metadata` - a map `string -> string` containing screencast track metadata to be sent to the server. -- `simulcastConfig` - current [SimulcastConfig](#SimulcastConfig) of a screencast track -- `toggleScreencastTrackEncoding(encoding: TrackEncoding)` - toggles simulcast encoding of a screencast track on/off. Arguments: - - `encoding: TrackEncoding` - encoding to toggle -- `setScreencastTrackEncodingBandwidth(encoding: TrackEncoding, bandwidth: BandwidthLimit)` - updates maximum bandwidth for the given simulcast encoding of the screencast track. Arguments: - - `encoding: TrackEncoding` - encoding to update - - `bandwidth: BandwidthLimit` - [BandwidthLimit](#trackbandwidthlimit) to set -- `setScreencastTrackBandwidth(bandwidth: BandwidthLimit)` - updates maximum bandwidth for the screencast track. This value directly translates to quality of the stream and the amount of RTP packets being sent. In case simulcast is enabled bandwidth is split between all of the variant streams proportionally to their resolution. Arguments: - - `bandwidth: BandwidthLimit` - [BandwidthLimit](#trackbandwidthlimit) to set - -Under the hood the screencast is just given participant's another video track. However for convenience the library creates a fake screencasting participant. The library recognizes a screencast track by `type: "screencasting"` metadata in screencasting video track. - -## `usePeerMetadata()` - -This hook manages user's metadata. Use it to for example update when user is muted etc. - -### Returns - -An object containing: - -- `updatePeerMetadata(metatada: Metadata)` - a function that updates user's metadata on the server. Arguments: - - `metatada: Metadata` - a map `string -> string` containing user's track metadata to be sent to the server. - -## `useVideoTrackMetadata()` - -This hook manages video track metadata. - -### Returns - -An object containing: - -- `updateVideoTrackMetadata(metatada: Metadata)` - a function that updates video metadata on the server. Arguments: - - `metatada: Metadata` - a map `string -> string` containing video track metadata to be sent to the server. - -## `useAudioTrackMetadata()` - -This hook manages audio track metadata. - -### Returns - -An object containing: - -- `updateAudioTrackMetadata(metatada: Metadata)` - a function that updates audio metadata on the server. Arguments: - - `metatada: Metadata` - a map `string -> string` containing audio track metadata to be sent to the server. - -## `useAudioSettings()` - -This hook manages audio settings. - -### Returns - -An object containing: - -- `toggleSpeakerphone()` - a function that toggles the speakerphone on/off. Supported only on Android -- `isSpeakerphoneOn` - `boolean`, `true` if the speakerphone is on. The speakerphone is on by default. - -## `` - -A component used for rendering participant's video and audio. You can add some basic View styling. - -Props: - -- `participantId: string` -- id of the participant which you want to render. -- `videoLayout: VideoLayout` -- `FILL` or `FIT` - it works just like RN `Image` component. `FILL` fills the whole view with video and it may cut some parts of the video. `FIT` scales the video so the whole video is visible, but it may leave some empty space in the view. Default: `FILL`. - -## `useSimulcast()` - -This hook manages the simulcast configuration of a video track. - -### Returns - -An object containing: - -- `simulcastConfig` - current [SimulcastConfig](#SimulcastConfig) of a video track -- `setTargetTrackEncoding(peerId: string, encoding: TrackEncoding)` - sets track encoding that server should send to the client library. The encoding will be sent whenever it is available. If choosen encoding is temporarily unavailable, some other encoding will be sent until choosen encoding becomes active again. Arguments: - - `peerId: string` - id of a peer whose track encoding you want to select - - `encoding: TrackEncoding` - encoding to select -- `toggleVideoTrackEncoding(encoding: TrackEncoding)` - toggles encoding of a video track on/off. Arguments: - - `encoding: TrackEncoding` - encoding to toggle -- `setVideoTrackEncodingBandwidth(encoding: TrackEncoding, bandwidth: BandwidthLimit)` - updates maximum bandwidth for the given simulcast encoding of the video track. Arguments: - - `encoding: TrackEncoding` - encoding to update - - `bandwidth: BandwidthLimit` - [BandwidthLimit](#trackbandwidthlimit) to set - -## `useBandwidthLimit()` - -This hook manages the bandwidth limit of a video track. - -### Returns - -An object containing: - -- `setVideoTrackBandwidth(bandwidth: BandwidthLimit)` - updates maximum bandwidth for the video track. This value directly translates to quality of the stream and the amount of RTP packets being sent. In case simulcast is enabled bandwidth is split between all of the variant streams proportionally to their resolution. Arguments: - -- `bandwidth: BandwidthLimit` - [BandwidthLimit](#trackbandwidthlimit) to set - -## `SimulcastConfig` - -A type describing simulcast configuration. - -At the moment, simulcast track is initialized in three versions - low, medium and high. -High resolution is the original track resolution, while medium and low resolutions -are the original track resolution scaled down by 2 and 4 respectively. - -`type SimulcastConfig` - -- `enabled: boolean` -- whether to simulcast track or not. By default simulcast is disabled. -- `activeEncodings: TrackEncoding[]` -- list of active encodings. Encoding can be one of `"h"` (original encoding), `"m"` (scaled down x2), `"l"` (scaled down x4). - -## `TrackBandwidthLimit` - -A type describing bandwidth limitation of a track, including simulcast and non-simulcast tracks. Can be `BandwidthLimit` or `SimulcastBandwidthLimit`. - -- `type BandwidthLimit` - Type describing maximal bandwidth that can be used, in kbps. 0 is interpreted as unlimited bandwidth. -- `type SimulcastBandwidthLimit` - Type describing bandwidth limit for simulcast track. It is a mapping `encoding -> BandwidthLimit`. If encoding isn't present in this mapping, it will be assumed that this particular encoding shouldn't have any bandwidth limit. - ### Developing To release a new version of the lib just run `yarn release`, follow the prompts to bump version, make tags, commits and upload to npm To release a new version of the example app install fastlane, get upload key password and firebase auth json from the devs, update `~/.gradle/gradle.properties` like this: @@ -493,5 +271,5 @@ Pro tip: when developing set backend url in `.env.development`. This project has been built and is maintained thanks to the support from [dscout](https://dscout.com/) and [Software Mansion](https://swmansion.com). -dscout +dscout Software Mansion diff --git a/package.json b/package.json index eabfb118..530d1501 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,8 @@ "prepublishOnly": "expo-module prepublishOnly", "expo-module": "expo-module", "release": "release-it", - "releaseApp": "cd example/android && fastlane deploy" + "releaseApp": "cd example/android && fastlane deploy", + "docs": "sed 's/\\.github\\/images/media/g' README.md > README_docs.md && typedoc src/index.tsx --media ./.github/images --readme README_docs.md && rm README_docs.md" }, "keywords": [ "react-native", @@ -51,6 +52,8 @@ "react": "16.13.1", "react-native": "0.67.3", "release-it": "^15.2.0", + "typedoc": "^0.23.16", + "typedoc-plugin-mark-react-functional-components": "^0.2.2", "typescript": "^4.1.3" }, "peerDependencies": { diff --git a/src/index.tsx b/src/index.tsx index 8ac650c9..33f21da0 100644 --- a/src/index.tsx +++ b/src/index.tsx @@ -36,8 +36,17 @@ export type Metadata = { [key: string]: string }; export type SocketConnectionParams = { [key: string]: any }; export type Participant = { + /** + * id used to identify a participant + */ id: string; + /** + * used to indicate participant type. + */ type: ParticipantType; + /** + * a map `string -> string` containing participant metadata from the server + */ metadata: Metadata; }; @@ -69,34 +78,100 @@ export enum ScreencastQuality { export type TrackEncoding = 'l' | 'm' | 'h'; +/** + * A type describing simulcast configuration. + * + * At the moment, simulcast track is initialized in three versions - low, medium and high. + * High resolution is the original track resolution, while medium and low resolutions are + * the original track resolution scaled down by 2 and 4 respectively. + */ export type SimulcastConfig = { + /** + * whether to simulcast track or not. By default simulcast is disabled. + */ enabled: boolean; + /** + * list of active encodings. Encoding can be one of `"h"` (original encoding), `"m"` (scaled down x2), `"l"` (scaled down x4). + */ activeEncodings: TrackEncoding[]; }; +/** + * Type describing maximal bandwidth that can be used, in kbps. 0 is interpreted as unlimited bandwidth. + */ export type BandwidthLimit = number; +/** + * Type describing bandwidth limit for simulcast track. It is a mapping `encoding -> BandwidthLimit`. If encoding isn't present in this mapping, + * it will be assumed that this particular encoding shouldn't have any bandwidth limit. + */ export type SimulcastBandwidthLimit = Map; +/** + * A type describing bandwidth limitation of a track, including simulcast and non-simulcast tracks. Can be `BandwidthLimit` or `SimulcastBandwidthLimit`. + */ export type TrackBandwidthLimit = BandwidthLimit | SimulcastBandwidthLimit; -export type ConnectionOptions = Partial<{ +export type ConnectionOptions = { + /** + * resolution + aspect ratio of local video track, one of: `QVGA_169`, `VGA_169`, `QHD_169`, `HD_169`, + * `FHD_169`, `QVGA_43`, `VGA_43`, `QHD_43`, `HD_43`, `FHD_43`. Note that quality might be worse than + * specified due to device capabilities, internet connection etc. + * @default `VGA_169` + */ quality: VideoQuality; + /** + * whether to flip the dimensions of the video, that is whether to film in vertical orientation. + * @default `true` + */ flipVideo: boolean; + /** + * a map `string -> string` containing user metadata to be sent to the server. Use it to send for example user display name or other options. + */ userMetadata: Metadata; + /** + * a map `string -> string` containing video track metadata to be sent to the server. + */ videoTrackMetadata: Metadata; + /** + * a map `string -> string` containing audio track metadata to be sent to the server. + */ audioTrackMetadata: Metadata; + /** + * SimulcastConfig of a video track. By default simulcast is disabled. + */ simulcastConfig: SimulcastConfig; + /** + * bandwidth limit of a video track. By default there is no bandwidth limit. + */ maxBandwidth: TrackBandwidthLimit; + /** + * a map `string -> string` containing connection params passed to the socket. + */ connectionParams: SocketConnectionParams; -}>; +}; -export type ScreencastOptions = Partial<{ +export type ScreencastOptions = { + /** + * Resolution + fps of screencast track, one of: `VGA`, `HD5`, `HD15`, `FHD15`, `FHD30`. + * Note that quality might be worse than specified due to device capabilities, internet + * connection etc. + * @default `HD15`` + */ quality: ScreencastQuality; + /** + * a map `string -> string` containing screencast track metadata to be sent to the server + */ screencastMetadata: Metadata; + /** + * SimulcastConfig of a screencast track. By default simulcast is disabled. + */ simulcastConfig: SimulcastConfig; + /** + * bandwidth limit of a screencast track. By default there is no bandwidth limit. + */ maxBandwidth: TrackBandwidthLimit; -}>; +}; const defaultSimulcastConfig = () => ({ enabled: false, @@ -106,6 +181,10 @@ const defaultSimulcastConfig = () => ({ let videoSimulcastConfig: SimulcastConfig = defaultSimulcastConfig(); let screencastSimulcastConfig: SimulcastConfig = defaultSimulcastConfig(); +/** + * The hook used to manage a connection with membrane server. + * @returns An object with functions to manage membrane server connection and `error` if connection failed. + */ export function useMembraneServer() { const [error, setError] = useState(null); // prevent user from calling connect methods multiple times @@ -125,12 +204,23 @@ export function useMembraneServer() { lock.current = false; }; - const connect = useCallback( + /** + * Connects to a room. + * @returns A promise that resolves on success or rejects in case of an error. + */ + const connect: ( + /** + * server url + */ + url: string, + roomName: string, + connectionOptions?: Partial + ) => Promise = useCallback( withLock( ( url: string, roomName: string, - connectionOptions: ConnectionOptions = {} + connectionOptions: Partial = {} ): Promise => { setError(null); videoSimulcastConfig = @@ -141,7 +231,11 @@ export function useMembraneServer() { [] ); - const joinRoom = useCallback( + /** + * Call this after successfully connecting with the server to join the room. Other participants' tracks will be sent and the user will be visible to other room participants. + * @returns A promise that resolves on success or rejects in case of an error. + */ + const joinRoom: () => Promise = useCallback( withLock((): Promise => { setError(null); return Membrane.join(); @@ -149,16 +243,29 @@ export function useMembraneServer() { [] ); - const disconnect = useCallback( + /** + * Call this to gracefully disconnect from the server. After that you can connect again. + * @returns A promise that resolves on success or rejects in case of an error. + */ + const disconnect: () => Promise = useCallback( withLock((): Promise => { setError(null); return Membrane.disconnect(); }), [] ); - return { connect, disconnect, joinRoom, error }; + return { + connect, + disconnect, + joinRoom, + error, + }; } +/** + * This hook provides live updates of room participants. + * @returns An array of room participants. + */ export function useRoomParticipants() { const [participants, setParticipants] = useState([]); @@ -180,6 +287,9 @@ export function useRoomParticipants() { return participants; } +/** + * This hook can toggle camera on/off and provides current camera state. + */ export function useCameraState() { const [isCameraOn, setIsCameraOn] = useState(false); @@ -191,6 +301,9 @@ export function useCameraState() { return () => eventListener.remove(); }, []); + /** + * Function to toggle camera on/off + */ const toggleCamera = useCallback(async () => { const state = await Membrane.toggleCamera(); setIsCameraOn(state); @@ -199,6 +312,9 @@ export function useCameraState() { return { isCameraOn, toggleCamera }; } +/** + * This hook can toggle microphone on/off and provides current microphone state. + */ export function useMicrophoneState() { const [isMicrophoneOn, setIsMicrophoneOn] = useState(false); @@ -210,6 +326,9 @@ export function useMicrophoneState() { return () => eventListener.remove(); }, []); + /** + * Function to toggle microphone on/off + */ const toggleMicrophone = useCallback(async () => { const state = await Membrane.toggleMicrophone(); setIsMicrophoneOn(state); @@ -218,10 +337,18 @@ export function useMicrophoneState() { return { isMicrophoneOn, toggleMicrophone }; } +/** + * Function that's toggles between front and back camera. By default the front camera is used. + * @returns A promise that resolves when camera is toggled. + */ export function flipCamera(): Promise { return Membrane.flipCamera(); } +/** + * This hook can toggle screen sharing on/off and provides current screencast state. + * @returns An object with functions to manage screencast. + */ export function useScreencast() { const [isScreencastOn, setIsScreencastOn] = useState(false); const [simulcastConfig, setSimulcastConfig] = useState( @@ -239,8 +366,16 @@ export function useScreencast() { return () => {}; }, []); + /** + * Toggles the screencast on/off + * + * Under the hood the screencast is just given participant's another video track. + * However for convenience the library creates a fake screencasting participant. + * The library recognizes a screencast track by `type: "screencasting"` metadata in + * screencasting video track. + */ const toggleScreencast = useCallback( - async (screencastOptions: ScreencastOptions = {}) => { + async (screencastOptions: Partial = {}) => { const state = await Membrane.toggleScreencast(screencastOptions); if (Platform.OS === 'android') { setIsScreencastOn(state); @@ -252,6 +387,10 @@ export function useScreencast() { [] ); + /** + * a function that updates screencast track metadata on the server + * @param metadata a map `string -> string` containing screencast track metadata to be sent to the server + */ const updateScreencastTrackMetadata = useCallback( async (metadata: Metadata) => { await Membrane.updateScreencastTrackMetadata(metadata); @@ -259,6 +398,10 @@ export function useScreencast() { [] ); + /** + * Toggles simulcast encoding of a screencast track on/off + * @param encoding encoding to toggle + */ const toggleScreencastTrackEncoding = useCallback( async (encoding: TrackEncoding) => { screencastSimulcastConfig = await Membrane.toggleScreencastTrackEncoding( @@ -269,6 +412,11 @@ export function useScreencast() { [] ); + /** + * updates maximum bandwidth for the given simulcast encoding of the screencast track + * @param encoding encoding to update + * @param bandwidth BandwidthLimit to set + */ const setScreencastTrackEncodingBandwidth = useCallback( async (encoding: TrackEncoding, bandwidth: BandwidthLimit) => { await Membrane.setScreencastTrackEncodingBandwidth(encoding, bandwidth); @@ -276,6 +424,13 @@ export function useScreencast() { [] ); + /** + * updates maximum bandwidth for the screencast track. This value directly translates + * to quality of the stream and the amount of RTP packets being sent. In case simulcast + * is enabled bandwidth is split between all of the variant streams proportionally to + * their resolution + * @param bandwidth BandwidthLimit to set + */ const setScreencastTrackBandwidth = useCallback( async (bandwidth: BandwidthLimit) => { await Membrane.setScreencastTrackBandwidth(bandwidth); @@ -294,30 +449,57 @@ export function useScreencast() { }; } +/** + * This hook manages user's metadata. Use it to for example update when user is muted etc. + */ export function usePeerMetadata() { + /** + * a function that updates user's metadata on the server + * @param metadata a map `string -> string` containing user's track metadata to be sent to the server + */ const updatePeerMetadata = useCallback(async (metadata: Metadata) => { await Membrane.updatePeerMetadata(metadata); }, []); return { updatePeerMetadata }; } +/** + * This hook manages video track metadata. + */ export function useVideoTrackMetadata() { + /** + * a function that updates video metadata on the server. + * @param metadata a map string -> string containing video track metadata to be sent to the server + */ const updateVideoTrackMetadata = useCallback(async (metadata: Metadata) => { await Membrane.updateVideoTrackMetadata(metadata); }, []); return { updateVideoTrackMetadata }; } +/** + * This hook manages audio track metadata. + */ export function useAudioTrackMetadata() { + /** + * a function that updates audio metadata on the server + * @param metadata a map `string -> string` containing audio track metadata to be sent to the server + */ const updateAudioTrackMetadata = useCallback(async (metadata: Metadata) => { await Membrane.updateAudioTrackMetadata(metadata); }, []); return { updateAudioTrackMetadata }; } +/** + * This hook manages audio settings. + */ export function useAudioSettings() { const [isSpeakerphoneOn, setIsSpeakerphoneOn] = useState(true); + /** + * function that toggles the speakerphone on/off. Supported only on Android + */ const toggleSpeakerphone = useCallback(async () => { if (Platform.OS !== 'android') { console.warn( @@ -331,10 +513,23 @@ export function useAudioSettings() { return { toggleSpeakerphone, isSpeakerphoneOn }; } +/** + * This hook manages the simulcast configuration of a video track. + * @returns An object with functions and data to manage simulcast configuration. + */ export function useSimulcast() { const [simulcastConfig, setSimulcastConfig] = useState(videoSimulcastConfig); + /** + * sets track encoding that server should send to the client library. + * The encoding will be sent whenever it is available. If choosen encoding is + * temporarily unavailable, some other encoding will be sent until choosen encoding + * becomes active again. + * + * @param peerId id of a peer whose track encoding you want to select + * @param encoding encoding to select + */ const setTargetTrackEncoding = useCallback( async (peerId: string, encoding: TrackEncoding) => { await Membrane.setTargetTrackEncoding(peerId, encoding); @@ -342,6 +537,10 @@ export function useSimulcast() { [] ); + /** + * toggles encoding of a video track on/off + * @param encoding encoding to toggle + */ const toggleVideoTrackEncoding = useCallback( async (encoding: TrackEncoding) => { videoSimulcastConfig = await Membrane.toggleVideoTrackEncoding(encoding); @@ -350,6 +549,11 @@ export function useSimulcast() { [] ); + /** + * updates maximum bandwidth for the given simulcast encoding of the video track + * @param encoding encoding to update + * @param bandwidth BandwidthLimit to set + */ const setVideoTrackEncodingBandwidth = useCallback( async (encoding: TrackEncoding, bandwidth: BandwidthLimit) => { await Membrane.setVideoTrackEndodingEncodingBandwidth( @@ -368,7 +572,17 @@ export function useSimulcast() { }; } +/** + * This hook manages the bandwidth limit of a video track. + */ export function useBandwidthLimit() { + /** + * updates maximum bandwidth for the video track. This value directly translates + * to quality of the stream and the amount of RTP packets being sent. In case simulcast + * is enabled bandwidth is split between all of the variant streams proportionally to + * their resolution. + * @param BandwidthLimit to set + */ const setVideoTrackBandwidth = useCallback( async (bandwidth: BandwidthLimit) => { await Membrane.setVideoTrackBandwidth(bandwidth); @@ -379,14 +593,26 @@ export function useBandwidthLimit() { return { setVideoTrackBandwidth }; } -type VideoRendererProps = { +export type VideoRendererProps = { + /** + * id of the participant which you want to render. + */ participantId: string; + /** + * `FILL` or `FIT` - it works just like RN Image component. `FILL` fills the whole view + * with video and it may cut some parts of the video. `FIT` scales the video so the whole + * video is visible, but it may leave some empty space in the view. + * @default `FILL` + */ videoLayout?: VideoLayout; style?: ViewStyle; }; const ComponentName = 'VideoRendererView'; +/** + * A component used for rendering participant's video and audio. You can add some basic View styling. + */ export const VideoRendererView = UIManager.getViewManagerConfig(ComponentName) != null ? requireNativeComponent(ComponentName) diff --git a/yarn.lock b/yarn.lock index c3df133b..75e53318 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4167,6 +4167,13 @@ brace-expansion@^1.1.7: balanced-match "^1.0.0" concat-map "0.0.1" +brace-expansion@^2.0.1: + version "2.0.1" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.1.tgz#1edc459e0f0c548486ecf9fc99f2221364b9a0ae" + integrity sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA== + dependencies: + balanced-match "^1.0.0" + braces@^2.3.1: version "2.3.2" resolved "https://registry.yarnpkg.com/braces/-/braces-2.3.2.tgz#5979fd3f14cd531565e5fa2df1abfff1dfaee729" @@ -8718,6 +8725,11 @@ json5@^2.2.1: resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.1.tgz#655d50ed1e6f95ad1a3caababd2b0efda10b395c" integrity sha512-1hqLFMSrGHRHxav9q9gNjJ5EXznIxGVO09xQRrwplcS8qs28pZ8s8hupZAmqDwZUmVZ2Qb2jnyPOWcDH8m8dlA== +jsonc-parser@^3.0.0: + version "3.2.0" + resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.0.tgz#31ff3f4c2b9793f89c67212627c51c6394f88e76" + integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w== + jsonfile@^2.1.0: version "2.4.0" resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-2.4.0.tgz#3736a2b428b87bbda0cc83b53fa3d633a35c2ae8" @@ -9121,6 +9133,11 @@ lru-cache@^6.0.0: dependencies: yallist "^4.0.0" +lunr@^2.3.9: + version "2.3.9" + resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" + integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== + macos-release@^3.0.1: version "3.1.0" resolved "https://registry.yarnpkg.com/macos-release/-/macos-release-3.1.0.tgz#6165bb0736ae567ed6649e36ce6a24d87cbb7aca" @@ -9165,6 +9182,11 @@ map-visit@^1.0.0: dependencies: object-visit "^1.0.0" +marked@^4.0.19: + version "4.1.1" + resolved "https://registry.yarnpkg.com/marked/-/marked-4.1.1.tgz#2f709a4462abf65a283f2453dc1c42ab177d302e" + integrity sha512-0cNMnTcUJPxbA6uWmCmjWz4NJRe/0Xfk2NhXCUHjew9qJzFN20krFnsUe7QynwqOwa5m1fZ4UDg0ycKFVC0ccw== + merge-stream@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/merge-stream/-/merge-stream-2.0.0.tgz#52823629a14dd00c9770fb6ad47dc6310f2c1f60" @@ -9593,6 +9615,13 @@ minimatch@^3.0.2, minimatch@^3.0.4, minimatch@^3.1.2: dependencies: brace-expansion "^1.1.7" +minimatch@^5.1.0: + version "5.1.0" + resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-5.1.0.tgz#1717b464f4971b144f6aabe8f2d0b8e4511e09c7" + integrity sha512-9TPBGGak4nHfGZsPBohm9AWg6NoT7QTCehS3BIJABslyZbzxfV78QM2Y6+i741OPZIafFAaiiEMh5OyIrJPgtg== + dependencies: + brace-expansion "^2.0.1" + minimist@^1.1.1, minimist@^1.2.0, minimist@^1.2.5: version "1.2.5" resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.5.tgz#67d66014b66a6a8aaa0c083c5fd58df4e4e97602" @@ -11537,6 +11566,15 @@ shellwords@^0.1.1: resolved "https://registry.yarnpkg.com/shellwords/-/shellwords-0.1.1.tgz#d6b9181c1a48d397324c84871efbcfc73fc0654b" integrity sha512-vFwSUfQvqybiICwZY5+DAWIPLKsWO31Q91JSKl3UYv+K5c2QRPzn0qzec6QPu1Qc9eHYItiP3NdJqNVqetYAww== +shiki@^0.11.1: + version "0.11.1" + resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.11.1.tgz#df0f719e7ab592c484d8b73ec10e215a503ab8cc" + integrity sha512-EugY9VASFuDqOexOgXR18ZV+TbFrQHeCpEYaXamO+SZlsnT/2LxuLBX25GGtIrwaEVFXUAbUQ601SWE2rMwWHA== + dependencies: + jsonc-parser "^3.0.0" + vscode-oniguruma "^1.6.1" + vscode-textmate "^6.0.0" + side-channel@^1.0.4: version "1.0.4" resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.0.4.tgz#efce5c8fdc104ee751b25c58d4290011fa5ea2cf" @@ -12405,6 +12443,21 @@ typedarray-to-buffer@^3.1.5: dependencies: is-typedarray "^1.0.0" +typedoc-plugin-mark-react-functional-components@^0.2.2: + version "0.2.2" + resolved "https://registry.yarnpkg.com/typedoc-plugin-mark-react-functional-components/-/typedoc-plugin-mark-react-functional-components-0.2.2.tgz#9236bb71dc811b18a508946c58392e83f48144ca" + integrity sha512-4nk3NPD35bfd4cPRylqk/SjkOruU46tG8tJ+IDnpgidzDwf5yEyr1XL9gxCX5dZblCMExPbMhNweIY/kzSL+Nw== + +typedoc@^0.23.16: + version "0.23.16" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.23.16.tgz#09881ada725c2190ac5d3bb0edadcc5bfeda4bfe" + integrity sha512-rumYsCeNRXlyuZVzefD7050n7ptL2uudsCJg50dY0v/stKniqIlRpvx/F/6expC0/Q6Dbab+g/JpZuB7Sw90FA== + dependencies: + lunr "^2.3.9" + marked "^4.0.19" + minimatch "^5.1.0" + shiki "^0.11.1" + typescript@^4.0.2, typescript@^4.1.3: version "4.6.2" resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.6.2.tgz#fe12d2727b708f4eef40f51598b3398baa9611d4" @@ -12681,6 +12734,16 @@ vm2@^3.9.8: acorn "^8.7.0" acorn-walk "^8.2.0" +vscode-oniguruma@^1.6.1: + version "1.6.2" + resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.6.2.tgz#aeb9771a2f1dbfc9083c8a7fdd9cccaa3f386607" + integrity sha512-KH8+KKov5eS/9WhofZR8M8dMHWN2gTxjMsG4jd04YhpbPR91fUj7rYQ2/XjeHCJWbg7X++ApRIU9NUwM2vTvLA== + +vscode-textmate@^6.0.0: + version "6.0.0" + resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-6.0.0.tgz#a3777197235036814ac9a92451492f2748589210" + integrity sha512-gu73tuZfJgu+mvCSy4UZwd2JXykjK9zAZsfmDeut5dx/1a7FeTk0XwJsSuqQn+cuMCGVbIBfl+s53X4T19DnzQ== + w3c-hr-time@^1.0.1, w3c-hr-time@^1.0.2: version "1.0.2" resolved "https://registry.yarnpkg.com/w3c-hr-time/-/w3c-hr-time-1.0.2.tgz#0a89cdf5cc15822df9c360543676963e0cc308cd"