AIMS UI SDK

A React component library to quickly integrate AIMS API features into your frontend application.

Ask a Question

Installation

To work with the package you need to have npm (or other package manager) installed. The library is built for React applications only.

  npm install @aims-api/ui-sdk

Segment Tool component

It fetches data for audio seed, displays waveform, controls playback of audio, and also provides a tool for selecting a segment.

Features

• Waveform rendering (YouTube, Spotify, SoundCloud, TikTok, Vimeo, Apple Music and internal tracks)
• Playback control
• Segment selection

Requirements

• React 18+
• Node.js server environment (e.g. Next.js server, Express.js, Hono...) to setup API handlers for your app.
• Install @aims-api/aims-node to work seamlessly with AIMS API in Node.js environment, used mainly for fetching link and waveform data. The package also provides types that are used in the client components.

Getting Started

Prepare two async handlers for data fetching:

• getSeed (required) a callback used for feeding the SegmentTool with data. It has to return a promise with the seed data (see required type structure). This callback needs to make a request (see link-info in examples folder) with some private (env) variables to ensure the handler to work as intended. In case of the promise rejection, you need to propagate message about component malfunction to the user.
• fetchWaveformUrl (optional) during initialization it fetches waveform file from AIMS API, returns a promise with url, which is eventually read and rendered by peaks.js library. If not provided, waveform will be rendered only for sources that provide an audio file - SoundCloud, TikTok, Apple Music, internal tracks.

The component is exported as a React hook useSegmentTool, which returns:

• component SegmentTool (React UI Component)
• segmentToolConfig (JS Object)

  type SegmentToolConfig = {
    isAudioPlaying: boolean;
    segmentRange: { from: number | null; to: number | null}
  }

• togglePlayback (callback to play or pause audio)

It is important to memoize SegmentTool component to avoid unnecessary re-renders. Also have a look at SegmentToolComponentProps type to ensure valid prop structure.

// Only property that matters for memoization is an injected seed. If the value is null, we do not render this component.
const MemoizedSegmentTool = memo(SegmentTool, (prevProps, newProps) => prevProps.seed === newProps.seed)

All useful types are located in /src/types/SegmentTool.ts. They are also exported in root file, so you can work with them as is shown in the example bellow.

// To work with tracks from AIMS search results, we call them internal tracks, set seed properties as following
const internalTrackSeed: DiscoverySearch = {
  input: DiscoveryInputs.INTERNAL,
  title: 'track name' // string,
  internalTrack: {
    id: 'trackId', // string OR number 
    duration: 120, // number OR null
    audioUrl: 'AUDIO_URL', // mp3 or other audio file supported by peaks.js
    waveformUrl: 'WAVEFORM_URL', // optional parameter (if not provided waveform will be calculated from audio
    // file), url to "dat" file is recognized by peaks.js
  }
}

// In order to render uploaded track, you need to upload file into browser and use this seed structure
const uploadedTrackSeed: DiscoverySearch = {
  input: DiscoveryInputs.UPLOAD,
  isSegmentToolAvailable: true,
  title: 'uploaded track' // string,
  uploadInfo: {
    audioUrl: 'AUDIO_URL' // string e.g. 'blob:...',
    format: 'mp3', // string,
    duration: 120 // number OR null,
  },
}

Usage Example

• Full example is available in /examples/basic including api routes (Next.js notation)

import { ThemeProvider, useSegmentTool, type DiscoverySearch } from '@aims-api/ui-sdk'

/* type DiscoverySearch is located in /src/types/SegmentTool.ts */

const MyComponent = () => {
  const { segmentToolConfig, SegmentTool, togglePlayback } = useSegmentTool()
  const { isAudioPlaying, segmentRange } = segmentToolConfig

  return (
    <>
      <ThemeProvider theme={{
        /* structure corresponds with MUI theming (MUI is not part of this package though), 
        you may also change only one of the colors 
            
            palette: {
              background: {
                default: string (e.g. hex, rgb)
              }
              primary: {
                main: string,
                light: string,
                dark: string,
              }
            }
          */
      }}>
      <SegmentTool
        getSeed={/* () => Promise<DiscoverySearch | null> */}
        fetchWaveformUrl={/* optional, (url: string) => Promise<string> */}
        options={{ // all params are optional
          initialRange: {/* hardcoded range; from: number, to: number */},
          playButtonHidden: {/* hide play button; boolean */},
          playheadInitHidden: {/* hide playhead in its initial position (workaround 
          // with palette.background.default color); boolean */},
          segmentSelectionDisabled={/* disable selecting segment; boolean */}
        }}
      />
      </ThemeProvider>
      <button onClick={togglePlayback}>Play or Pause Audio</button>
      {/* Access configuration */}
      <div>Audio is playing: {isAudioPlaying}</div>
      <div>Selection starts: {segmentRange.from}, ends: {segmentRange.to}</div>
    </>
  )
}

Component state changes aren’t exported because our application does not interact with them. Upon receiving a seed, the waveform component initially displays a skeleton placeholder. Once the waveform data has been processed by the peaks.js library, the waveform appears instantly.

License

See LICENSE and NOTICE for more information.