AudioRecorder

Записывает микрофон в аудиофайл — голосовое сообщение, голосовую заметку — из плагина audio-recorder. Чтобы превратить речь в текст, бери SpeechRecognizer (Распознавание речи); запись видео недоступна (Справочник API).

  • записать голосовое сообщение с микрофона
  • показывать кнопку записи только там, где устройство может записывать (AudioRecorder.supported)
  • показывать живой индикатор уровня звука во время записи
  • останавливать запись самой по истечении лимита времени
  • поставить запись на паузу и продолжить
  • воспроизвести только что записанное
  • загрузить запись на сервер приложения
  • обработать отказ в разрешении на микрофон

Платформы: iOS и Android в приложении-вьюере le.codes, веб и веб-плеер; нет на десктопе и в headless-тестах и пока нет в iOS- или Android-приложении, собранном через lecodes app. Проверяй AudioRecorder.supported.

Обзор

TypeScript
const recorder = new AudioRecorder()
const status = UIText('Tap Record')
const meter = UIBox().style({ height: 6, width: 4, bgColor: '#e5484d', borderRadius: 3 })
recorder.addEventListener('level', v => meter.style({ width: 4 + v * 200 }))   // 0..1, десять раз в секунду

const finish = async () => {
  const { file, duration } = await recorder.stop()     // аудио-File и его длина в секундах
  meter.style({ width: 4 })
  status.text = `Recorded ${duration.toFixed(1)} s`
  new AudioPlayer(file).play()                         // воспроизвести
}
recorder.addEventListener('ended', () => { finish() })   // достигнут лимит в одну минуту

const toggle = async () => {
  if (recorder.state !== 'inactive') return finish()
  await recorder.start({ maxDuration: 60_000 })        // в первый раз спрашивает микрофон
  status.text = 'Recording… tap to stop'
}

UIScreen(
  AudioRecorder.supported
    ? UIButton(UIText('Record')).onClick(() => { toggle().catch(e => { status.text = e.message }) })
    : UIText('Recording is not available on this device'),
  meter, status,
).style({ pt: 'safe-top', p: 20, gap: 12 }).open()

Подключение рекордера: plugins в app.json

AudioRecorder нужен плагин audio-recorder, перечисленный в app.json приложения (один список на все платформы; в приложении-вьюере le.codes он есть, что бы ни было в списке):

JSON
{ "plugins": { "audio-recorder": "*" } }

AudioRecorder.supported равен true там, где хост зарегистрировал плагин; читай его, прежде чем показывать кнопку записи (как в «Обзоре»). Без плагина start() отклоняется.

  • В вебе записывает браузер (своим MediaRecorder), и только на безопасной странице: https или localhost. На простой http-странице или в браузере без MediaRecorder supported равен false.
  • lecodes app пока не знает этот плагин: синхронизация iOS- или Android-приложения, в app.json которого он перечислен, останавливается на Unknown plugin "audio-recorder". На телефоне он работает в приложении-вьюере le.codes.

Запись голосового сообщения: start и stop

start() начинает запись с микрофона; stop() её заканчивает и резолвится записью — аудио-File, его mimeType и duration. Один AudioRecorder делает одну запись за раз и переиспользуется: после stop() или cancel() он готов к новому start().

TypeScript
new AudioRecorder()                                     // ничего не открывается до start()
AudioRecorder.supported: boolean                      // у этого хоста есть плагин

recorder.start(options?: RecordOptions): Promise<void>  // сначала спрашивает микрофон
recorder.stop(): Promise<Recording>                     // запись; и после `ended` тоже
recorder.cancel(): void                                 // остановить и выбросить запись
recorder.state: 'inactive' | 'recording' | 'paused' | 'stopped'

interface RecordOptions {
  bitrate?: number       // килобиты в секунду; по умолчанию 64 (речь), 128 для музыки
  sampleRate?: number    // сэмплов в секунду; по умолчанию 44100 (в вебе — только подсказка)
  maxDuration?: number   // миллисекунды; потом останавливается сама (`ended`). По умолчанию без лимита
}
interface Recording {
  file: File             // recording.m4a / .webm / .ogg
  mimeType: string       // 'audio/mp4', 'audio/webm', … — см. «Какой формат у записи»
  duration: number       // секунды звука, без пауз
}
  • start(), пока запись идёт (recording, paused или stopped), отклоняется — сначала вызови stop() или cancel(). cancel(), когда ничего не идёт, ничего не делает.
  • state равен 'stopped' после того, как запись закончилась сама (ended); stop() всё равно её возвращает.

Индикатор уровня звука во время записи: событие level

Событие level даёт входной уровень микрофона, 0..1, примерно десять раз в секунду во время записи (не на паузе) — для индикатора или осциллограммы:

TypeScript
const recorder = new AudioRecorder()
const bar = UIBox().style({ height: 8, width: 2, bgColor: '#30a46c', borderRadius: 4 })
recorder.addEventListener('level', v => bar.style({ width: 2 + Math.min(1, v * 3) * 240 }))

const start = UIButton(UIText('Speak')).onClick(() => { recorder.start().catch(e => toast(e.message)) })
const stop = UIButton(UIText('Done')).onClick(() => { recorder.cancel(); bar.style({ width: 2 }) })

UIScreen(start, bar, stop).style({ pt: 'safe-top', p: 20, gap: 12 }).open()
Note

каждая платформа меряет уровень по-своему — iOS среднюю мощность, Android пик, веб удвоенный RMS, — поэтому тот же голос на Android даёт больше, чем на iOS. Масштабируй его для индикатора; не используй как порог «пользователь говорит».

Ограничение длины голосового сообщения: maxDuration и событие ended

Чтобы ограничить голосовое сообщение минутой или 30 секундами, передай maxDuration (миллисекунды) в start(): запись остановится сама, ended сработает с причиной, а запись будет ждать stop(), который вернёт то, что успело записаться:

TypeScript
const recorder = new AudioRecorder()
const status = UIText('')

recorder.addEventListener('ended', async reason => {
  // 'maxDuration' = лимит, 'interrupted' = телефонный звонок (iOS) или микрофон отобрали (веб),
  // 'failed' = сбой энкодера
  try {
    const { duration } = await recorder.stop()       // файл хранится до stop() или cancel()
    status.text = `Stopped (${reason}) after ${duration.toFixed(1)} s`
  } catch {
    status.text = 'Nothing was recorded'
  }
})

const record = UIButton(UIText('Record 30 s')).onClick(() => {
  recorder.start({ maxDuration: 30_000 }).then(() => { status.text = 'Recording…' }, e => { status.text = e.message })
})

UIScreen(record, status).style({ pt: 'safe-top', p: 20, gap: 12 }).open()
Note

в вебе maxDuration отсчитывается от start(), вместе с паузами.

Пауза и продолжение записи

pause() придерживает запись — уровень перестаёт приходить, duration не растёт, — а resume() продолжает её в тот же файл:

TypeScript
const recorder = new AudioRecorder()
const label = UIText('Pause')

const pauseOrResume = async () => {
  if (recorder.state === 'recording') { await recorder.pause(); label.text = 'Resume' }
  else if (recorder.state === 'paused') { await recorder.resume(); label.text = 'Pause' }
}

UIScreen(
  UIButton(UIText('Record')).onClick(() => { recorder.start().catch(e => toast(e.message)) }),
  UIButton(label).onClick(() => { pauseOrResume().catch(e => toast(e.message)) }),
).style({ pt: 'safe-top', p: 20, gap: 12 }).open()

pause() отклоняется, если состояние не 'recording', resume() — если не 'paused' (поэтому после ended отклоняются оба). В Android 6 паузы нет: там оба отклоняются с 'failed'.

Воспроизведение записи: AudioPlayer

file записи — источник для AudioPlayer (Медиа), который играет его из памяти: чтобы послушать, загружать ничего не нужно:

TypeScript
const recorder = new AudioRecorder()
let last: File | null = null

const stop = async () => { last = (await recorder.stop()).file }

UIScreen(
  UIButton(UIText('Record')).onClick(() => { recorder.start().catch(e => toast(e.message)) }),
  UIButton(UIText('Stop')).onClick(() => { stop().catch(e => toast(e.message)) }),
  UIButton(UIText('Play')).onClick(() => { if (last) new AudioPlayer(last).play() }),
).style({ pt: 'safe-top', p: 20, gap: 12 }).open()

Собственные записи телефонов (AAC в .m4a) играют везде; .webm, записанный в браузере, в iOS-плеере не играет (Какой формат у записи).

Загрузка записи на сервер

Чтобы загрузить голосовую запись на собственный сервер приложения, передай File записи в серверную функцию: параметр типа File — это загрузка, а поле t.file() её хранит (Хранимые файлы):

TypeScript
// voice.server.ts — выполняется на бэкенде приложения
const Voice = model({
  audio: t.file(),
  mimeType: t.string(),
  seconds: t.float(),
  createdAt: t.date().default("now"),
})
const db = defineDb({ Voice })

export async function sendVoice(audio: File, mimeType: string, seconds: number) {
  return db.voice.insert({ audio, mimeType, seconds })
}
TypeScript
// main.ts — приложение
import { sendVoice } from "./voice.server"

const recorder = new AudioRecorder()
const status = UIText('')

const send = async () => {
  const { file, mimeType, duration } = await recorder.stop()
  await sendVoice(file, mimeType, duration)          // байты идут вместе с вызовом
  status.text = 'Sent'
}
recorder.addEventListener('ended', () => { send().catch(e => { status.text = e.message }) })   // лимит

const toggle = async () => {
  if (recorder.state !== 'inactive') return send()
  await recorder.start({ maxDuration: 60_000 })
  status.text = 'Recording… tap to send'
}

UIScreen(
  UIButton(UIText('Voice message')).onClick(() => { toggle().catch(e => { status.text = e.message }) }),
  status,
).style({ pt: 'safe-top', p: 20, gap: 12 }).open()

Хранимый файл — не больше 10 МБ; минута речи при 64 кбит/с по умолчанию — около 480 КБ. audio.url строки — то, что играет AudioPlayer другого пользователя. Чтобы вместо этого отправить запись в другой HTTP API, положи File в FormData (Сеть).

Какой формат у записи: mimeType

Формат — это энкодер платформы, а mimeType говорит, какой:

Где Формат mimeType file.name
iOS, Android AAC в MPEG-4 'audio/mp4' recording.m4a
веб, веб-плеер то, что кодирует MediaRecorder браузера: MPEG-4, где браузер умеет (Safari умеет), иначе Opus в WebM 'audio/mp4', 'audio/webm' (или 'audio/ogg') recording.m4a / .webm / .ogg

Чат, сообщения которого должны играть на любом устройстве, перекодирует веб-WebM на своём сервере: iOS-плеер WebM не играет. Отправляй mimeType вместе с файлом (как выше): бэкенд читает type хранимого файла из его байтов, и файл только со звуком может прочитаться там как video/webm или video/mp4.

Разрешение на микрофон и ошибки

Первый start() спрашивает микрофон: на iOS и Android — диалогом разрешения хоста, в вебе — браузерным. Отказ отклоняет с 'denied'; код отклонения — e.message.

Вызов Отклоняется с Когда
start() 'denied' пользователь отказал в микрофоне (iOS спрашивает один раз: дальше включить можно только в Настройках)
start() 'failed' рекордер не смог стартовать: нет входа, звук занят звонком
start() Error на этом хосте нет плагина или запись уже идёт
pause() / resume() Error · 'failed' не идёт запись / не на паузе · Android 6
stop() 'failed' закодировать ничего не удалось (остановка сразу после старта на Android)

Чтобы спросить до первой записи или после отказа отправить пользователя в Настройки, используй permissions (Разрешения):

TypeScript
const recorder = new AudioRecorder()
const status = UIText('')

const record = async () => {
  try {
    await recorder.start()
    status.text = 'Recording…'
  } catch (e) {
    if (e.message !== 'denied') { status.text = `Could not record: ${e.message}`; return }
    status.text = 'Allow the microphone in Settings to record'
    permissions.openSettings()                     // страница приложения в системных настройках (не в вебе)
  }
}

UIScreen(UIButton(UIText('Record')).onClick(() => { record() }), status).style({ pt: 'safe-top', p: 20, gap: 12 }).open()

Смотрите также