carta1 1.3.0 → 1.5.0

package/README.md

@@ -58,7 +58,7 @@ signed 16-bit PCM WAVE output.
 | `-j, --json`          | Write AEA metadata and frame structure as JSON.      |
 | `-q, --quiet`         | Suppress normal output and progress.                 |
 | `-f, --force`         | Overwrite an existing output file.                   |
-| `-t, --title <title>` | Set the AEA title while encoding.                    |
+| `-t, --title <title>` | Set a UTF-8 AEA title (up to 255 encoded bytes).     |
 | `-b, --bias <value>`  | Set the bit-allocation bias; defaults to `1.0`.      |
 | `-m, --modes <modes>` | Fix low, mid, and high block modes, such as `0,0,0`. |
 | `-V, --version`       | Print the Carta1 version.                            |
@@ -184,8 +184,8 @@ npm test            # Run the test suite once
 npm run test:watch  # Re-run tests while editing
 npm run lint        # Check JavaScript and formatting
 npm run format      # Apply repository formatting
-npm run build       # Build the three browser bundles
-npm run check       # Run lint, tests, and the production build
+npm run build       # Build browser bundles and the WME plugin
+npm run check       # Run lint, tests, builds, and packaged WME checks
 ```
 
 Run `npm run check` before submitting a change. Pull requests and pushes run
@@ -201,3 +201,51 @@ implementation used to understand the ATRAC1 format and codec behavior.
 ## License
 
 ISC
+
+
+## Experimental Web MiniDisc encoder plugin
+
+`npm run build` also emits `dist/carta1.wme`, alongside the three existing
+browser bundles. GitHub Releases attach the WME, all three JavaScript bundles,
+and their source maps. The npm package includes the same build outputs. Release
+CDN links are pinned to that release's version.
+
+**Carta1 (ATRAC1, experimental)** is an ATRAC1 codec for standard MD SP, not
+ATRAC3 LP2/LP4 or ATRAC3PLUS Hi-MD. Current Web MiniDisc API v1 does not support
+software ATRAC1 output: its SP modes request PCM for the recorder to encode in
+hardware. Installing this plugin does not enable Carta1 recording in the
+unmodified app. All current API v1 codecs (PCM, MP3, AT3, A3+) are explicitly
+reported as unsupported so there is no silent hardware-encoding fallback.
+
+### Proposed host extension for testing
+
+The archive uses the standard API v1 SAR container and default encoder class,
+with the usual `init`, `deinit`, `getSupportFor`, `transcode`, and progress hooks.
+It adds two **proposed, nonstandard** export codec names, using the host's
+existing recording-mode names:
+
+| `exportParams.format` | PCM channels | Output |
+| --- | --- | --- |
+| `{ codec: 'SPS', bitrate: 292 }` | 2 | ATRAC1 stereo SP |
+| `{ codec: 'SPM', bitrate: 146 }` | 1 | ATRAC1 mono SP |
+
+Bitrates are nominal kbps; ATRAC1 uses 212-byte sound units per channel per
+512 samples at 44.1 kHz. The host's built-in FFmpeg decodes/resamples sources
+and optionally applies ReplayGain; the existing Carta1 worker encodes them.
+`transcode` returns raw sound units **without the 2048-byte AEA header**.
+Stereo sound units alternate left/right. Canonical priming and drain units
+are retained; gapless is not advertised and AEA timeline metadata is omitted.
+
+A host implementing this proposal must extend its export-codec interface,
+preserve SPS/SPM through capability checks and transcoding instead of mapping
+them to PCM, and route the result to a compatible pre-encoded ATRAC1 transfer
+path (such as a supported device's homebrew SP uploader). It must handle channel
+mode, transfer framing/padding, and device capabilities there. Ordinary SP PCM
+upload must never receive these compressed bytes. Neither the proposed names
+nor device transfer compatibility are part of the current WMD API contract;
+the WMD team can revise them when implementing support. No host changes are
+included here.
+
+`npm run test:wme` exercises the built archive and its bundled worker for both
+proposed formats, comparing the returned raw bytes with `encodeAeaPcm` across
+independent tracks. Lifecycle and failure tests run in the normal test suite.

package/bin/build-wme.js

@@ -0,0 +1,69 @@
+/** Package the bundled API v1 module and existing worker as a WME SAR archive.
+ * Wire format: asivery/webminidisc src/services/audio/apiv1/external-archive.ts
+ * (9637bed5), with big-endian lengths and metadata.json as the first entry.
+ */
+import { readFile, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+// The host imports blobs; relative source-map URLs cannot resolve there.
+function bundledScript(contents) {
+  return Buffer.from(
+    Buffer.from(contents)
+      .toString('utf8')
+      .replace(/^\/\/# sourceMappingURL=.*$/gm, '')
+  )
+}
+
+export function createWmeArchive(metadata, index, worker) {
+  const parts = [Buffer.from('SARFile')]
+  const subMagic = Buffer.from('Web MiniDisc Dynamic Encoder')
+  const length = Buffer.alloc(2)
+  length.writeUInt16BE(subMagic.length)
+  parts.push(length, subMagic)
+  for (const [name, contents] of [
+    ['metadata.json', Buffer.from(JSON.stringify(metadata))],
+    ['index.js', bundledScript(index)],
+    ['worker.js', bundledScript(worker)],
+  ]) {
+    const filename = Buffer.from(name)
+    const nameLength = Buffer.alloc(2)
+    nameLength.writeUInt16BE(filename.length)
+    const size = Buffer.alloc(4)
+    size.writeUInt32BE(contents.length)
+    parts.push(nameLength, filename, size, contents)
+  }
+  const archive = Buffer.concat(parts)
+  if (archive.length > 50 * 1024 * 1024) {
+    throw new RangeError('WME archive exceeds the host 50 MiB limit')
+  }
+  return archive
+}
+
+async function main() {
+  const root = new URL('../', import.meta.url)
+  const pkg = JSON.parse(await readFile(new URL('package.json', root), 'utf8'))
+  const [index, worker] = await Promise.all([
+    readFile(new URL('dist/wme/index.js', root)),
+    readFile(new URL(`dist/${pkg.name}-worker.min.js`, root)),
+  ])
+  const archive = createWmeArchive(
+    {
+      encoderId: pkg.name,
+      userFriendlyName: 'Carta1 (ATRAC1, experimental)',
+      description:
+        'ATRAC1 codec for standard MD SP stereo/mono. Experimental: requires host support for software ATRAC1; current Web MiniDisc API v1 is unsupported.',
+      version: pkg.version,
+      encoderDependencies: [],
+      apiVersion: '1',
+    },
+    index,
+    worker
+  )
+  const output = new URL(`dist/${pkg.name}.wme`, root)
+  await writeFile(output, archive)
+  console.log(`Built ${fileURLToPath(output)} (${archive.length} bytes)`)
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  await main()
+}

package/bin/cli.js

@@ -21,14 +21,13 @@ import wav from 'wav'
 
 import { AudioProcessor } from '../codec/boundary/processor.js'
 import { AeaReader } from '../codec/boundary/reader.js'
-import { AeaFile } from '../codec/boundary/container.js'
+import { AeaFile, validateAeaTitle } from '../codec/boundary/container.js'
 import { deserializeFrame } from '../codec/syntax/frame.js'
 import { EncoderOptions } from '../codec/core/options.js'
 import {
   SAMPLE_RATE,
   SAMPLES_PER_FRAME,
   BITRATE_PER_CHANNEL,
-  AEA_TITLE_SIZE,
   AEA_HEADER_SIZE,
   SOUND_UNIT_SIZE,
 } from '../codec/core/constants.js'
@@ -48,7 +47,7 @@ function formatTime(seconds) {
 }
 
 /**
- * Validate AEA title for length and ASCII encoding
+ * Validate an AEA title for its fixed-width UTF-8 field.
  *
  * @param {string} title - Title to validate
  * @returns {Object} Validation result
@@ -56,31 +55,7 @@ function formatTime(seconds) {
  * @returns {string} [returns.error] - Error message if invalid
  */
 function validateTitle(title) {
-  if (!title) {
-    return { valid: true }
-  }
-
-  // Check ASCII encoding
-  for (let i = 0; i < title.length; i++) {
-    const charCode = title.charCodeAt(i)
-    if (charCode > 127) {
-      return {
-        valid: false,
-        error: `Title contains non-ASCII character at position ${i}: "${title[i]}"`,
-      }
-    }
-  }
-
-  // Check length (AEA_TITLE_SIZE includes null terminator)
-  const maxLength = AEA_TITLE_SIZE - 1
-  if (title.length > maxLength) {
-    return {
-      valid: false,
-      error: `Title is too long (${title.length} chars). Maximum allowed: ${maxLength} characters`,
-    }
-  }
-
-  return { valid: true }
+  return validateAeaTitle(title)
 }
 
 /**
@@ -703,7 +678,7 @@ async function main() {
     .option('-f, --force', 'Overwrite output file if it exists')
     .option(
       '-t, --title <title>',
-      'Custom title for AEA file metadata (encoding only)'
+      'Custom UTF-8 title for AEA file metadata (encoding only)'
     )
     .option(
       '-b, --bias <value>',

package/codec/boundary/container.js

@@ -14,6 +14,29 @@ import {
 } from '../core/constants.js'
 import { AEA_MAGIC } from '../core/tables.js'
 
+const UTF8_ENCODER = new TextEncoder()
+const UTF8_DECODER = new TextDecoder()
+
+/**
+ * Validate a title for the fixed-width AEA title field.
+ *
+ * @param {string} title
+ * @returns {{valid: boolean, error?: string}}
+ */
+export function validateAeaTitle(title) {
+  const byteLength = UTF8_ENCODER.encode(title).length
+  const maxByteLength = AEA_TITLE_SIZE - 1
+
+  if (byteLength > maxByteLength) {
+    return {
+      valid: false,
+      error: `Title is too long (${byteLength} UTF-8 bytes). Maximum allowed: ${maxByteLength} bytes`,
+    }
+  }
+
+  return { valid: true }
+}
+
 /**
  * AEA file-format handler.
  */
@@ -39,10 +62,9 @@ export class AeaFile {
     const view = new DataView(header.buffer)
     header.set(AEA_MAGIC, 0)
 
-    const titleBytes = new TextEncoder().encode(title)
-    header.set(
-      titleBytes.subarray(0, Math.min(titleBytes.length, AEA_TITLE_SIZE - 1)),
-      AEA_TITLE_OFFSET
+    UTF8_ENCODER.encodeInto(
+      title,
+      header.subarray(AEA_TITLE_OFFSET, AEA_TITLE_OFFSET + AEA_TITLE_SIZE - 1)
     )
     view.setUint32(AEA_FRAME_COUNT_OFFSET, frameCount, true)
     header[AEA_CHANNEL_COUNT_OFFSET] = channelCount
@@ -81,7 +103,7 @@ export class AeaFile {
     const titleEnd = header.indexOf(0, AEA_TITLE_OFFSET)
     const titleLength =
       titleEnd === -1 ? AEA_TITLE_SIZE : titleEnd - AEA_TITLE_OFFSET
-    const title = new TextDecoder().decode(
+    const title = UTF8_DECODER.decode(
       header.subarray(AEA_TITLE_OFFSET, AEA_TITLE_OFFSET + titleLength)
     )
 

package/codec/boundary/wme.js

@@ -0,0 +1,189 @@
+/** Experimental ATRAC1 host extension; see README's WME contract.
+ * API v1's current codec union does not include SPS/SPM. No PCM fallback.
+ */
+import { AeaFile } from './container.js'
+import { AEA_HEADER_SIZE, SOUND_UNIT_SIZE } from '../core/constants.js'
+
+const PROFILES = {
+  SPS: { bitrate: 292, channels: 2 },
+  SPM: { bitrate: 146, channels: 1 },
+}
+
+export default class CartaWmeEncoder {
+  static customConstructionParameters = []
+
+  constructor(api) {
+    this.api = api
+    this.ffmpeg = api.getBuiltinEncoder('ffmpeg')
+    this.workerURL = null
+    this.worker = null
+    this.rejectJob = null
+    this.busy = false
+  }
+
+  async init() {
+    if (this.workerURL) return
+    try {
+      await this.ffmpeg.init()
+      this.workerURL = URL.createObjectURL(
+        new Blob([this.api.getOwnFile('worker.js')], {
+          type: 'text/javascript',
+        })
+      )
+    } catch (error) {
+      await this.ffmpeg.deinit()
+      throw error
+    }
+  }
+
+  async deinit() {
+    this.rejectJob?.(new Error('Encoder was stopped'))
+    this.worker?.terminate()
+    this.worker = null
+    if (this.workerURL) URL.revokeObjectURL(this.workerURL)
+    this.workerURL = null
+    await this.ffmpeg.deinit()
+  }
+
+  getSupportFor(codec) {
+    if (Object.hasOwn(PROFILES, codec)) {
+      return {
+        state: 'perfect',
+        gapless: false,
+        bitrates: [PROFILES[codec].bitrate],
+      }
+    }
+    return { state: 'unsupported', gapless: false }
+  }
+
+  getUserFriendyStageName(stage) {
+    if (stage === 'carta') return 'Encoding ATRAC1...'
+    if (stage === 'ffmpeg') return 'Preparing audio...'
+    return this.ffmpeg.getUserFriendyStageName(stage)
+  }
+
+  async transcode(source, sourceFileName, exportParams, progress) {
+    if (!this.workerURL) throw new Error('Encoder is not initialized')
+    if (this.busy) throw new Error('Encoder is already processing a track')
+    const { codec, bitrate } = exportParams.format
+    if (
+      !Object.hasOwn(PROFILES, codec) ||
+      bitrate !== PROFILES[codec].bitrate
+    ) {
+      throw new RangeError(
+        'Unsupported carta1 recording format (experimental SPS/SPM host extension required)'
+      )
+    }
+    this.busy = true
+    try {
+      return await this.encodeAtrac(
+        source,
+        sourceFileName,
+        exportParams,
+        progress
+      )
+    } finally {
+      this.busy = false
+    }
+  }
+
+  async encodeAtrac(source, sourceFileName, exportParams, progress) {
+    const { channels } = PROFILES[exportParams.format.codec]
+    const extension = sourceFileName.split('.').pop()
+    const inputName = `carta1-input.${/^[a-z0-9]+$/i.test(extension) ? extension : 'audio'}`
+    const outputName = 'carta1-pcm.f32'
+    const process = this.ffmpeg.ffmpegProcess
+    try {
+      progress?.({ stage: 'ffmpeg', progress: 0, total: 1 })
+      await process.write(inputName, source)
+      // Preserve host resampling/ReplayGain, overriding its default stereo for SPM.
+      const command = this.ffmpeg.createFfmpegParams(
+        exportParams,
+        'f32le',
+        `-ac ${channels} -c:a pcm_f32le`
+      )
+      await process.transcode(inputName, outputName, command)
+      const { data } = await process.read(outputName)
+      const stride = channels * 4
+      if (data.byteLength === 0 || data.byteLength % stride !== 0) {
+        throw new RangeError('Expected nonempty channel-aligned float32 PCM')
+      }
+      const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
+      const samples = data.byteLength / stride
+      const pcmData = Array.from(
+        { length: channels },
+        () => new Float32Array(samples)
+      )
+      for (let sample = 0; sample < samples; sample++) {
+        for (let channel = 0; channel < channels; channel++) {
+          pcmData[channel][sample] = view.getFloat32(
+            sample * stride + channel * 4,
+            true
+          )
+        }
+      }
+      progress?.({ stage: 'ffmpeg', progress: 1, total: 1 })
+      progress?.({ stage: 'carta', progress: 0, total: 1 })
+      const aea = await this.encodeInWorker(pcmData)
+      if (aea.byteLength <= AEA_HEADER_SIZE) {
+        throw new Error('Worker returned an incompatible ATRAC1 AEA file')
+      }
+      const info = AeaFile.parseHeader(aea.subarray(0, AEA_HEADER_SIZE))
+      const payloadLength = aea.byteLength - AEA_HEADER_SIZE
+      if (
+        info.channelCount !== channels ||
+        payloadLength % (SOUND_UNIT_SIZE * channels) !== 0 ||
+        info.frameCount * SOUND_UNIT_SIZE !== payloadLength
+      ) {
+        throw new Error('Worker returned an incompatible ATRAC1 AEA file')
+      }
+      progress?.({ stage: 'carta', progress: 1, total: 1 })
+      // Proposed host contract: raw 212-byte sound units, no AEA header.
+      // Stereo units alternate L/R. Keep canonical priming and drain units.
+      return aea.slice(AEA_HEADER_SIZE)
+    } finally {
+      // FFmpeg 0.6 tracks pending FS jobs by action, not job ID. Parallel
+      // removals overwrite the resolver and leave one promise pending forever.
+      for (const filename of [inputName, outputName]) {
+        try {
+          await process.remove(filename)
+        } catch {
+          // A failed conversion may not have created both temporary files.
+        }
+      }
+    }
+  }
+
+  async encodeInWorker(pcmData) {
+    const worker = new Worker(this.workerURL)
+    this.worker = worker
+    try {
+      const result = await new Promise((resolve, reject) => {
+        this.rejectJob = reject
+        worker.onmessage = ({ data }) => {
+          if (data.jobId !== 1) return
+          if (data.error) reject(new Error(data.error))
+          else resolve(data.result)
+        }
+        worker.onerror = (event) =>
+          reject(new Error(event.message || 'Codec worker failed'))
+        worker.onmessageerror = () =>
+          reject(new Error('Invalid codec worker response'))
+        worker.postMessage(
+          {
+            jobId: 1,
+            type: 'encode',
+            pcmData,
+            options: {},
+          },
+          pcmData.map((channel) => channel.buffer)
+        )
+      })
+      return new Uint8Array(await result.aeaBlob.arrayBuffer())
+    } finally {
+      this.rejectJob = null
+      worker.terminate()
+      this.worker = null
+    }
+  }
+}