npm install --save react-modern-audio-player

import AudioPlayer from "react-modern-audio-player";
const playList = [
  {
    name: "name",
    writer: "writer",
    img: "image.jpg",
    src: "audio.mp3",
    id: 1,
  },
];
function Player() {
  return <AudioPlayer playList={playList} />;
}

// app/page.tsx — Server Component, no 'use client' needed
import AudioPlayer from "react-modern-audio-player";
const playList = [
  {
    name: "track",
    writer: "artist",
    img: "cover.jpg",
    src: "audio.mp3",
    id: 1,
  },
];
export default function Page() {
  return <AudioPlayer playList={playList} activeUI={{ playButton: true }} />;
}

"use client";
// app/player/page.tsx — Client Component required for hooks & compound pattern
import AudioPlayer, { useAudioPlayer } from "react-modern-audio-player";
function Controls() {
  const { isPlaying, togglePlay } = useAudioPlayer();
  return <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>;
}
export default function PlayerPage() {
  return (
    <AudioPlayer playList={playList}>
      <AudioPlayer.CustomComponent id="controls">
        <Controls />
      </AudioPlayer.CustomComponent>
    </AudioPlayer>
  );
}

interface AudioPlayerProps {
  playList: PlayList;
  audioInitialState?: InitialStates;
  audioRef?: React.MutableRefObject<HTMLAudioElement>;
  activeUI?: ActiveUI;
  customIcons?: CustomIcons;
  coverImgsCss?: CoverImgsCss;
  placement?: {
    player?: PlayerPlacement;
    playList?: PlayListPlacement;
    interface?: InterfacePlacement;
    volumeSlider?: VolumeSliderPlacement;
    speedSelector?: SpeedSelectorPlacement;
    timeTooltip?: TimeTooltipPlacement;
  };
  rootContainerProps?: RootContainerProps;
  colorScheme?: "light" | "dark";
}

type PlayList = Array<AudioData>;
type AudioData = {
  src: string;
  id: number;
  name?: string;
  writer?: string;
  img?: string;
  description?: string | ReactNode;
  customTrackInfo?: string | ReactNode;
  // Long-form & streaming (all optional, opt-in)
  isLive?: boolean;
  duration?: number;
  peaks?: number[] | number[][];
  preload?: "none" | "metadata" | "auto";
};

const playList = [
  {
    id: 1,
    src: "/podcast-3h.mp3",
    name: "Long episode",
    duration: 3 * 60 * 60,
  },
  {
    id: 2,
    src: "https://stream.example.com/live",
    name: "Live radio",
    isLive: true,
  },
];

function App() {
  const [tracks, setTracks] = useState<PlayList>([]);
  useEffect(() => {
    fetchTracks().then(setTracks);
  }, []);
  // Safe — the player mounts with no audio source and activates once tracks arrive.
  return <AudioPlayer playList={tracks} />;
}

type InitialStates = Omit<
  React.AudioHTMLAttributes<HTMLAudioElement>,
  "autoPlay"
> & {
  isPlaying?: boolean;
  repeatType?: RepeatType;
  volume?: number;
  currentTime?: number;
  duration?: number;
  curPlayId: number;
  playListExpanded?: boolean;
};

type ActiveUI = {
  all: boolean;
  playButton: boolean;
  playList: PlayListUI;
  prevNnext: boolean;
  volume: boolean;
  volumeSlider: boolean;
  repeatType: boolean;
  trackTime: boolean;
  trackInfo: boolean;
  artwork: boolean;
  progress: ProgressUI;
  playbackRate: boolean;
};
type ProgressUI = "waveform" | "bar" | false;
type PlayListUI = "sortable" | "unSortable" | false;

type CustomIcons = {
  play: ReactNode;
  pause: ReactNode;
  prev: ReactNode;
  next: ReactNode;
  repeatOne: ReactNode;
  repeatAll: ReactNode;
  repeatNone: ReactNode;
  repeatShuffle: ReactNode;
  volumeFull: ReactNode;
  volumeHalf: ReactNode;
  volumeMuted: ReactNode;
  playList: ReactNode;
};

interface CoverImgsCss {
  artwork?: React.CSSProperties;
  listThumbnail?: React.CSSProperties;
}

type PlayerPlacement =
  | "bottom"
  | "top"
  | "bottom-left"
  | "bottom-right"
  | "top-left"
  | "top-right";
type VolumeSliderPlacement = "bottom" | "top" | "left" | "right";
type SpeedSelectorPlacement = "bottom" | "top" | "left" | "right";
type TimeTooltipPlacement = "top" | "bottom";
type PlayListPlacement = "bottom" | "top";
type InterfacePlacement = {
  templateArea?: InterfaceGridTemplateArea;
  customComponentsArea?: InterfaceGridCustomComponentsArea<TMaxLength>;
  itemCustomArea?: InterfaceGridItemArea;
};
type InterfacePlacementKey =
  | Exclude<keyof ActiveUI, "all" | "prevNnext" | "trackTime">
  | "trackTimeCurrent"
  | "trackTimeDuration";
type InterfacePlacementValue = "row1-1" | "row1-2" | "row1-3" | "row1-4" | ... more ... | "row10-10"
/** if you apply custom components, values must be "row1-1" ~ any more */
type InterfaceGridTemplateArea = Record<InterfacePlacementKey,InterfacePlacementValue>;
type InterfaceGridCustomComponentsArea = Record<componentId,InterfacePlacementValue>;
type InterfaceGridItemArea = Partial<Record<InterfacePlacementKey, string>>;
  /** example
   * progress : 2-4
   * repeatBtn : row1-4 / 2 / row1-4 / 10
   *
   * check MDN - grid area
   * https://developer.mozilla.org/ko/docs/Web/CSS/grid-area
   */

const defaultInterfacePlacement = {
  templateArea: {
    artwork: "row1-1",
    trackInfo: "row1-2",
    trackTimeCurrent: "row1-3",
    trackTimeDuration: "row1-4",
    progress: "row1-5",
    repeatType: "row1-6",
    volume: "row1-7",
    playButton: "row1-8",
    playList: "row1-9",
    playbackRate: "row1-10",
  },
};

@media (prefers-color-scheme: dark) {
  .rmap-player-provider {
    --rm-audio-player-interface-container: #1e1e1e;
    /* override other variables as needed */
  }
}

.rmap-player-provider {
  --rm-audio-player-text-color: #2c2c2c;
  --rm-audio-player-shadow: 0 0 0;
  --rm-audio-player-interface-container: #f5f5f5;
  --rm-audio-player-volume-background: #ccc;
  --rm-audio-player-volume-panel-background: #f2f2f2;
  --rm-audio-player-volume-panel-border: #ccc;
  --rm-audio-player-volume-thumb: #5c5c5c;
  --rm-audio-player-volume-fill: rgba(0, 0, 0, 0.5);
  --rm-audio-player-volume-track: #ababab;
  --rm-audio-player-track-current-time: #0072f5;
  --rm-audio-player-track-duration: #8c8c8c;
  --rm-audio-player-progress-bar: #0072f5;
  --rm-audio-player-progress-bar-background: #393939;
  --rm-audio-player-tooltip-background: #f2f2f2;
  --rm-audio-player-waveform-cursor: #4b4b4b;
  --rm-audio-player-waveform-background: var(
    --rm-audio-player-progress-bar-background
  );
  --rm-audio-player-waveform-bar: var(--rm-audio-player-progress-bar);
  --rm-audio-player-sortable-list: #eaeaea;
  --rm-audio-player-sortable-list-button-active: #0072f5;
  --rm-audio-player-selected-list-item-background: #b3b3b3;
}

import AudioPlayer, { useAudioPlayer } from "react-modern-audio-player";
function PlayerControls() {
  const {
    isPlaying,
    currentTrack,
    currentTime,
    duration,
    togglePlay,
    next,
    prev,
    seek,
    setVolume,
    setTrack,
  } = useAudioPlayer();
  const timeLabel = `${currentTime.toFixed(0)}s / ${duration.toFixed(0)}s`;
  return (
    <div>
      <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>
      <button onClick={prev}>Prev</button>
      <button onClick={next}>Next</button>
      <button onClick={() => seek(30)}>+30s</button>
      <button onClick={() => setVolume(0.5)}>Volume 50%</button>
      <button onClick={() => setTrack(1)}>Track 2</button>
      <p>
        {currentTrack?.name} — {timeLabel}
      </p>
    </div>
  );
}
function App() {
  const playList = [{ id: 1, src: "audio.mp3", name: "Track 1" }];
  return (
    <AudioPlayer playList={playList}>
      <PlayerControls />
    </AudioPlayer>
  );
}

import {
  useAudioPlayerPlayback,
  useAudioPlayerTrack,
  useAudioPlayerVolume,
  useAudioPlayerTime,
  useAudioPlayerElement,
} from "react-modern-audio-player";
// Only re-renders on play/pause and repeat type changes
function PlayButton() {
  const { isPlaying, togglePlay } = useAudioPlayerPlayback();
  return <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>;
}
// Only re-renders on time updates
function TimeDisplay() {
  const { currentTime, duration } = useAudioPlayerTime();
  return (
    <span>
      {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
    </span>
  );
}

import {
  usePlaybackContext, // curAudioState: { isPlaying, repeatType, volume, muted, isLoadedMetaData }
  useTrackContext, // playList, curIdx, curPlayId
  useUIContext, // activeUI, interfacePlacement, playListPlacement, playerPlacement, volumeSliderPlacement
  useResourceContext, // elementRefs, customIcons, coverImgsCss
} from "react-modern-audio-player";
const MyComponent = () => {
  const { curAudioState } = usePlaybackContext();
  return <span>{curAudioState.isPlaying ? "Playing" : "Paused"}</span>;
};

import AudioPlayer, {
  useAudioPlayer,
  InterfacePlacement,
  DEFAULT_INTERFACE_GRID_BOUND,
} from "react-modern-audio-player";
const activeUI: ActiveUI = {
  all: true,
};
// `as 12` pins the literal type — TS arithmetic widens
// `DEFAULT_INTERFACE_GRID_BOUND + 1` to `number`, which would erase grid-coord
const TOTAL_INTERFACE_GRID_BOUND = (DEFAULT_INTERFACE_GRID_BOUND + 1) as 12;
// `row1-${DEFAULT_INTERFACE_GRID_BOUND}` resolves to `"row1-11"` —
// the first cell beyond the default template area (which fills 1..10).
const customComponentGridArea = `row1-${DEFAULT_INTERFACE_GRID_BOUND}`;
const placement = {
  interface: {
    customComponentsArea: {
      playerCustomComponent: customComponentGridArea,
    },
  } as InterfacePlacement<typeof TOTAL_INTERFACE_GRID_BOUND>,
  /**
   * The generic on `InterfacePlacement<N>` is an exclusive upper bound on grid
   * indices — usable cells are `1..(N - 1)`. Default is
   * `DEFAULT_INTERFACE_GRID_BOUND` (= 11), giving cells `1..10` which the
   * built-in template area already occupies (e.g. `playbackRate` at `row1-10`).
   * To reserve an additional cell for the custom component, pass `<N + 1>` —
   * here `<12>` makes `row1-11` a valid coordinate.
   */
};
const CustomComponent = () => {
  const { currentTime, duration, seek, isPlaying, togglePlay } =
    useAudioPlayer();
  return (
    <>
      <button onClick={() => seek(currentTime + 30)}>+30s</button>
      <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>
      <span>
        {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
      </span>
    </>
  );
};
<AudioPlayer playList={playList} placement={placement} activeUI={activeUI}>
  <AudioPlayer.CustomComponent id="playerCustomComponent">
    <CustomComponent />
  </AudioPlayer.CustomComponent>
</AudioPlayer>;

// Remove the default volume, re-place it with a custom gridArea
<AudioPlayer playList={playList} activeUI={{ all: true, volume: false }}>
  <AudioPlayer.Volume gridArea="row1-5" />
</AudioPlayer>

// Re-place the full Play + Prev + Next group at a custom area
<AudioPlayer
  playList={playList}
  activeUI={{ all: true, playButton: false }} // hide the preset transport
>
  <AudioPlayer.PlayButton gridArea="row1-3" />
</AudioPlayer>
// Same compound, but render Play only — Prev / Next hidden by activeUI.prevNnext
<AudioPlayer
  playList={playList}
  activeUI={{ all: true, playButton: false, prevNnext: false }}
>
  <AudioPlayer.PlayButton gridArea="row1-3" />
</AudioPlayer>

import AudioPlayer, {
  PrevBtn,
  PlayBtn,
  NextBtn,
} from "react-modern-audio-player";
<AudioPlayer
  playList={playList}
  activeUI={{ all: true, playButton: false }} // hide the preset transport
  placement={{
    interface: { customComponentsArea: { "custom-transport": "row1-3" } },
  }}
>
  <AudioPlayer.CustomComponent id="custom-transport">
    <div className="my-transport">
      <PrevBtn isVisible />
      <PlayBtn />
      <NextBtn isVisible />
    </div>
  </AudioPlayer.CustomComponent>
</AudioPlayer>;

<AudioPlayer playList={[]}>
  <AudioPlayer.PlayListEmpty>
    <div className="my-empty">Playlist is empty</div>
  </AudioPlayer.PlayListEmpty>
</AudioPlayer>

function App() {
  return (
    <div>
      <AudioPlayer
        playList={playList}
        audioInitialState={{
          muted: true,
          volume: 0.2,
          curPlayId: 1,
        }}
        placement={{
          interface: {
            templateArea: {
              trackTimeDuration: "row1-5",
              progress: "row1-4",
              playButton: "row1-6",
              repeatType: "row1-7",
              volume: "row1-8",
            },
          },
          player: "bottom-left",
        }}
        activeUI={{
          all: true,
          progress: "waveform",
        }}
      />
    </div>
  );
}