Include useKrispNoiseFilter in generated docs, + related improvements (#1055)

bcherry · web-flow · commit 146272c1654c · 2024-12-20T19:56:15.000-08:00
diff --git a/.changeset/brown-taxis-appear.md b/.changeset/brown-taxis-appear.md
@@ -0,0 +1,7 @@
+---
+"@livekit/components-core": patch
+"@livekit/components-react": patch
+"@livekit/api-documenter": patch
+---
+
+Include useKrispNoiseFilter in generated docs
diff --git a/packages/core/etc/components-core.api.md b/packages/core/etc/components-core.api.md
@@ -221,7 +221,7 @@ export type GridLayoutInfo = {
 export function isEqualTrackRef(a?: TrackReferenceOrPlaceholder, b?: TrackReferenceOrPlaceholder): boolean;
 
 // @public (undocumented)
-export function isLocal(p: Participant): p is LocalParticipant;
+export function isLocal(p: Participant): boolean;
 
 // @public
 export function isMobileBrowser(): boolean;
@@ -235,7 +235,7 @@ export function isParticipantTrackReferencePinned(trackRef: TrackReference, pinS
 export function isPlaceholderReplacement(currentTrackRef: TrackReferenceOrPlaceholder, nextTrackRef: TrackReferenceOrPlaceholder): boolean;
 
 // @public (undocumented)
-export function isRemote(p: Participant): p is RemoteParticipant;
+export function isRemote(p: Participant): boolean;
 
 // @public (undocumented)
 export function isSourcesWithOptions(sources: SourcesArray): sources is TrackSourceWithOptions[];
diff --git a/packages/core/tsdoc.json b/packages/core/tsdoc.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": [ "../../tsdoc.json" ]
+}
diff --git a/packages/react/api-extractor.json b/packages/react/api-extractor.json
@@ -16,5 +16,5 @@
    * DEFAULT VALUE: ""
    */
   "extends": "../../api-extractor-shared.json",
-  "mainEntryPointFilePath": "./dist/index.d.ts"
+  "mainEntryPointFilePath": "./dist/index.docs.d.ts"
 }
diff --git a/packages/react/etc/components-react.api.md b/packages/react/etc/components-react.api.md
@@ -13,12 +13,14 @@ import { CreateLocalTracksOptions } from 'livekit-client';
 import { DataPublishOptions } from 'livekit-client';
 import { DisconnectReason } from 'livekit-client';
 import { HTMLAttributes } from 'react';
+import { KrispNoiseFilterProcessor } from '@livekit/krisp-noise-filter';
 import { LocalAudioTrack } from 'livekit-client';
 import { LocalParticipant } from 'livekit-client';
 import { LocalTrack } from 'livekit-client';
 import { LocalTrackPublication } from 'livekit-client';
 import { LocalVideoTrack } from 'livekit-client';
 import { MediaDeviceFailure } from 'livekit-client';
+import { NoiseFilterOptions } from '@livekit/krisp-noise-filter';
 import { Participant } from 'livekit-client';
 import { ParticipantEvent } from 'livekit-client';
 import type { ParticipantKind } from 'livekit-client';
@@ -162,7 +164,7 @@ export const ChatIcon: (props: SVGProps<SVGSVGElement>) => React_2.JSX.Element;
 
 export { ChatMessage }
 
-// Warning: (ae-forgotten-export) The symbol "ChatOptions" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "ChatOptions" needs to be exported by the entry point index.docs.d.ts
 //
 // @public (undocumented)
 export interface ChatProps extends React_2.HTMLAttributes<HTMLDivElement>, ChatOptions {
@@ -445,12 +447,12 @@ export interface MediaDeviceSelectProps extends Omit<React_2.HTMLAttributes<HTML
     track?: LocalAudioTrack | LocalVideoTrack;
 }
 
-// Warning: (ae-forgotten-export) The symbol "LegacyReceivedChatMessage" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "LegacyReceivedChatMessage" needs to be exported by the entry point index.docs.d.ts
 //
 // @public @deprecated (undocumented)
 export type MessageDecoder = (message: Uint8Array) => LegacyReceivedChatMessage;
 
-// Warning: (ae-forgotten-export) The symbol "LegacyChatMessage" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "LegacyChatMessage" needs to be exported by the entry point index.docs.d.ts
 //
 // @public @deprecated (undocumented)
 export type MessageEncoder = (message: LegacyChatMessage) => Uint8Array;
@@ -500,7 +502,7 @@ export function ParticipantContextIfNeeded(props: React_2.PropsWithChildren<{
     participant?: Participant;
 }>): React_2.JSX.Element;
 
-// Warning: (ae-forgotten-export) The symbol "RequireAtLeastOne" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "RequireAtLeastOne" needs to be exported by the entry point index.docs.d.ts
 //
 // @beta (undocumented)
 export type ParticipantIdentifier = RequireAtLeastOne<{
@@ -629,14 +631,14 @@ export const ScreenShareIcon: (props: SVGProps<SVGSVGElement>) => React_2.JSX.El
 // @internal (undocumented)
 export const ScreenShareStopIcon: (props: SVGProps<SVGSVGElement>) => React_2.JSX.Element;
 
-// Warning: (ae-forgotten-export) The symbol "LogExtension" needs to be exported by the entry point index.d.ts
-// Warning: (ae-forgotten-export) The symbol "SetLogExtensionOptions" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "LogExtension" needs to be exported by the entry point index.docs.d.ts
+// Warning: (ae-forgotten-export) The symbol "SetLogExtensionOptions" needs to be exported by the entry point index.docs.d.ts
 //
 // @public
 export function setLogExtension(extension: LogExtension, options?: SetLogExtensionOptions): void;
 
-// Warning: (ae-forgotten-export) The symbol "LogLevel" needs to be exported by the entry point index.d.ts
-// Warning: (ae-forgotten-export) The symbol "SetLogLevelOptions" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "LogLevel" needs to be exported by the entry point index.docs.d.ts
+// Warning: (ae-forgotten-export) The symbol "SetLogLevelOptions" needs to be exported by the entry point index.docs.d.ts
 //
 // @public
 export function setLogLevel(level: LogLevel, options?: SetLogLevelOptions): void;
@@ -692,19 +694,19 @@ export type TrackReference = {
     source: Track.Source;
 };
 
-// Warning: (ae-forgotten-export) The symbol "TrackReferencePlaceholder" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "TrackReferencePlaceholder" needs to be exported by the entry point index.docs.d.ts
 //
 // @public (undocumented)
 export type TrackReferenceOrPlaceholder = TrackReference | TrackReferencePlaceholder;
 
-// Warning: (ae-forgotten-export) The symbol "ToggleSource" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "ToggleSource" needs to be exported by the entry point index.docs.d.ts
 //
 // @public
 export const TrackToggle: <T extends ToggleSource>(props: TrackToggleProps<T> & React_2.RefAttributes<HTMLButtonElement>) => React_2.ReactNode;
 
 // @public (undocumented)
 export interface TrackToggleProps<T extends ToggleSource> extends Omit<React_2.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
-    // Warning: (ae-forgotten-export) The symbol "CaptureOptionsBySource" needs to be exported by the entry point index.d.ts
+    // Warning: (ae-forgotten-export) The symbol "CaptureOptionsBySource" needs to be exported by the entry point index.docs.d.ts
     //
     // (undocumented)
     captureOptions?: CaptureOptionsBySource<T>;
@@ -793,8 +795,8 @@ export function useConnectionState(room?: Room): ConnectionState_2;
 // @public (undocumented)
 export function useCreateLayoutContext(): LayoutContextType;
 
-// Warning: (ae-forgotten-export) The symbol "ReceivedDataMessage" needs to be exported by the entry point index.d.ts
-// Warning: (ae-forgotten-export) The symbol "UseDataChannelReturnType" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "ReceivedDataMessage" needs to be exported by the entry point index.docs.d.ts
+// Warning: (ae-forgotten-export) The symbol "UseDataChannelReturnType" needs to be exported by the entry point index.docs.d.ts
 //
 // @public
 export function useDataChannel<T extends string>(topic: T, onMessage?: (msg: ReceivedDataMessage<T>) => void): UseDataChannelReturnType<T>;
@@ -829,7 +831,7 @@ export function useEnsureTrackRef(trackRef?: TrackReferenceOrPlaceholder): Track
 // @alpha
 export function useFacingMode(trackReference: TrackReferenceOrPlaceholder): 'user' | 'environment' | 'left' | 'right' | 'undefined';
 
-// Warning: (ae-forgotten-export) The symbol "FeatureContext" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "FeatureContext" needs to be exported by the entry point index.docs.d.ts
 // Warning: (ae-internal-missing-underscore) The name "useFeatureContext" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal (undocumented)
@@ -887,6 +889,21 @@ export function useIsRecording(room?: Room): boolean;
 // @public
 export function useIsSpeaking(participant?: Participant): boolean;
 
+// @beta
+export function useKrispNoiseFilter(options?: useKrispNoiseFilterOptions): {
+    setNoiseFilterEnabled: (enable: boolean) => Promise<void>;
+    isNoiseFilterEnabled: boolean;
+    isNoiseFilterPending: boolean;
+    processor: KrispNoiseFilterProcessor | undefined;
+};
+
+// @beta (undocumented)
+export interface useKrispNoiseFilterOptions {
+    // @internal (undocumented)
+    filterOptions?: NoiseFilterOptions;
+    trackRef?: TrackReferenceOrPlaceholder;
+}
+
 // @public
 export function useLayoutContext(): LayoutContextType;
 
@@ -1183,20 +1200,20 @@ export interface UseTokenOptions {
 // @public
 export function useTrackByName(name: string, participant?: Participant): TrackReferenceOrPlaceholder;
 
-// Warning: (ae-forgotten-export) The symbol "TrackMutedIndicatorReturnType" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "TrackMutedIndicatorReturnType" needs to be exported by the entry point index.docs.d.ts
 //
 // @public
 export function useTrackMutedIndicator(trackRef?: TrackReferenceOrPlaceholder): TrackMutedIndicatorReturnType;
 
 // @public
 export function useTrackRefContext(): TrackReferenceOrPlaceholder;
 
-// Warning: (ae-forgotten-export) The symbol "SourcesArray" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "SourcesArray" needs to be exported by the entry point index.docs.d.ts
 //
 // @public
 export function useTracks<T extends SourcesArray = Track.Source[]>(sources?: T, options?: UseTracksOptions): UseTracksHookReturnType<T>;
 
-// Warning: (ae-forgotten-export) The symbol "TrackSourceWithOptions" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "TrackSourceWithOptions" needs to be exported by the entry point index.docs.d.ts
 //
 // @public (undocumented)
 export type UseTracksHookReturnType<T> = T extends Track.Source[] ? TrackReference[] : T extends TrackSourceWithOptions[] ? TrackReferenceOrPlaceholder[] : never;
@@ -1316,11 +1333,11 @@ export type WidgetState = {
 
 // Warnings were encountered during analysis:
 //
-// src/context/layout-context.ts:10:3 - (ae-forgotten-export) The symbol "PinContextType" needs to be exported by the entry point index.d.ts
-// src/context/layout-context.ts:11:3 - (ae-forgotten-export) The symbol "WidgetContextType" needs to be exported by the entry point index.d.ts
-// src/hooks/useGridLayout.ts:27:6 - (ae-forgotten-export) The symbol "GridLayoutInfo" needs to be exported by the entry point index.d.ts
-// src/hooks/useMediaDeviceSelect.ts:47:29 - (ae-forgotten-export) The symbol "SetMediaDeviceOptions" needs to be exported by the entry point index.d.ts
-// src/hooks/useTrackTranscription.ts:43:38 - (ae-forgotten-export) The symbol "ReceivedTranscriptionSegment" needs to be exported by the entry point index.d.ts
+// src/context/layout-context.ts:10:3 - (ae-forgotten-export) The symbol "PinContextType" needs to be exported by the entry point index.docs.d.ts
+// src/context/layout-context.ts:11:3 - (ae-forgotten-export) The symbol "WidgetContextType" needs to be exported by the entry point index.docs.d.ts
+// src/hooks/useGridLayout.ts:27:6 - (ae-forgotten-export) The symbol "GridLayoutInfo" needs to be exported by the entry point index.docs.d.ts
+// src/hooks/useMediaDeviceSelect.ts:47:29 - (ae-forgotten-export) The symbol "SetMediaDeviceOptions" needs to be exported by the entry point index.docs.d.ts
+// src/hooks/useTrackTranscription.ts:43:38 - (ae-forgotten-export) The symbol "ReceivedTranscriptionSegment" needs to be exported by the entry point index.docs.d.ts
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/packages/react/src/hooks/cloud/krisp/useKrispNoiseFilter.ts b/packages/react/src/hooks/cloud/krisp/useKrispNoiseFilter.ts
@@ -6,33 +6,38 @@ import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
 import { useLocalParticipant } from '../../..';
 
 /**
- * @alpha
+ * @beta
  */
 export interface useKrispNoiseFilterOptions {
   /**
-   * by default the hook will use the localParticipant's microphone track publication.
-   * You can override this behavior by passing in a target TrackReference here
+   * The track reference to use for the noise filter (defaults: local microphone track)
    */
   trackRef?: TrackReferenceOrPlaceholder;
+  /**
+   * @internal
+   */
   filterOptions?: NoiseFilterOptions;
 }
 
 /**
- * This hook is a convenience helper for enabling Krisp Enhanced Audio Noise Cancellation on LiveKit audio tracks.
- * It returns a `setNoiseFilterEnabled` method to conveniently toggle between enabled and disabled states.
+ * Enable the Krisp enhanced noise cancellation feature for local audio tracks.
+ *
+ * Defaults to the localParticipant's microphone track publication, but you can override this behavior by passing in a different track reference.
  *
- * @remarks Krisp noise filter is a feature that's only supported on LiveKit cloud plans
- * @alpha
+ * @package \@livekit/components-react/krisp
+ * @remarks This filter requires that you install the `@livekit/krisp-noise-filter` package and is supported only on {@link https://cloud.livekit.io | LiveKit Cloud}.
+ * @beta
  * @example
  * ```tsx
- *   const krisp = useKrispNoiseFilter();
- *   return <input
-        type="checkbox"
-        onChange={(ev) => krisp.setNoiseFilterEnabled(ev.target.checked)}
-        checked={krisp.isNoiseFilterEnabled}
-        disabled={krisp.isNoiseFilterPending}
-      />
+ * const krisp = useKrispNoiseFilter();
+ * return <input
+ *   type="checkbox"
+ *   onChange={(ev) => krisp.setNoiseFilterEnabled(ev.target.checked)}
+ *   checked={krisp.isNoiseFilterEnabled}
+ *   disabled={krisp.isNoiseFilterPending}
+ * />
  * ```
+ * @returns Use `setIsNoiseFilterEnabled` to enable/disable the noise filter.
  */
 export function useKrispNoiseFilter(options: useKrispNoiseFilterOptions = {}) {
   const [shouldEnable, setShouldEnable] = React.useState(false);
diff --git a/packages/react/src/hooks/useIsMuted.ts b/packages/react/src/hooks/useIsMuted.ts
@@ -16,10 +16,20 @@ export interface UseIsMutedOptions {
  * The `useIsMuted` hook is used to implement the `TrackMutedIndicator` or your custom implementation of it.
  * It returns a `boolean` that indicates if the track is muted or not.
  *
- * @example
+ * @example With a track reference
  * ```tsx
  * const isMuted = useIsMuted(track);
  * ```
+ *
+ * @example With a track source / participant
+ * ```tsx
+ * const isMuted = useIsMuted('camera', { participant });
+ * ```
+ *
+ * @param sourceOrTrackRef - Either a `TrackReference` or a `Track.Source` (see usage examples)
+ * @param options - Additional options when using a `Track.Source`
+ * @returns boolean indicating if the track is muted
+ *
  * @public
  */
 export function useIsMuted(trackRef: TrackReferenceOrPlaceholder): boolean;
diff --git a/packages/react/src/index.docs.ts b/packages/react/src/index.docs.ts
@@ -0,0 +1,12 @@
+/**
+ * Used to merge the exports from the main index.ts file with the exports from the cloud/krisp/useKrispNoiseFilter.ts file for docs generation.
+ */
+
+// Regular exports
+export * from './index';
+
+// Cloud/Krisp exports
+export {
+  useKrispNoiseFilter,
+  type useKrispNoiseFilterOptions,
+} from './hooks/cloud/krisp/useKrispNoiseFilter';
diff --git a/packages/react/tsdoc.json b/packages/react/tsdoc.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": [ "../../tsdoc.json" ]
+}
diff --git a/tooling/api-documenter/src/documenters/MarkdownDocumenter.ts b/tooling/api-documenter/src/documenters/MarkdownDocumenter.ts
diff --git a/tooling/api-documenter/src/nodes/Callout.ts b/tooling/api-documenter/src/nodes/Callout.ts
diff --git a/tsdoc.json b/tsdoc.json

Original file line number	Diff line number	Diff line change
`@@ -16,5 +16,5 @@`
`16`	`16`	`* DEFAULT VALUE: ""`
`17`	`17`	`*/`
`18`	`18`	`"extends": "../../api-extractor-shared.json",`
`19`		`- "mainEntryPointFilePath": "./dist/index.d.ts"`
	`19`	`+ "mainEntryPointFilePath": "./dist/index.docs.d.ts"`
`20`	`20`	`}`