@aims-api/ui-sdk v0.0.3

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 environemnt, 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}
  }

• pauseAudio (callback)

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.

Usage Example

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

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

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

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

  return (
    <div>
      <SegmentTool
        getSeed={/* () => Promise<DiscoverySearch | null> */}
        fetchWaveformUrl={/* (url: string) => Promise<string> */}
        disableSegmentSelection={/* undefined | true */}
      />
      <button onClick={pauseAudio}>Pause Audio</button>
      {/* Access configuration */}
      <div>Audio is playing: {isAudioPlaying}</div>
      <div>Selection starts: {segmentRange.from}, ends: {segmentRange.to}</div>
    </div>
  )
}

License

See LICENSE and NOTICE for more information.