morse-coder

Lightweight Morse code encoding, decoding, and audio tooling for Node.js and modern bundlers. Convert plain text to Morse, parse Morse back to text, and generate WAV audio for playback or distribution.

Project homepage: https://morse-coder.com
Source repository: https://github.com/cabbagehao/cabbagehao

Features

• Complete Morse code maps for letters, digits, and common punctuation marks
• Bidirectional text ↔ Morse translation with customizable separators
• High-quality PCM/WAV synthesis with playback and filesystem export helpers
• Type definitions included for seamless TypeScript integration
• Zero dependencies beyond the lightweight play-sound helper

Requirements

• Node.js 18 or newer (ESM module support)
• Optional: a system audio player supported by play-sound (afplay, mpg123, mplayer, etc.) if you intend to call play()

Installation

npm install morse-coder

or with pnpm / yarn:

pnpm add morse-coder
yarn add morse-coder

Basic Usage

import { encode, decode, audio } from 'morse-coder';

const encoded = encode('SOS'); // ... --- ...
const decoded = decode('... --- ...'); // SOS

const player = audio('HELLO WORLD');
await player.play();            // start playback (requires external player)
await player.save('hello.wav'); // export to WAV

Encoding Options

import { encode } from 'morse-coder';

const morse = encode('Hello, world!', {
  letterSeparator: ' ',        // default: single space
  wordSeparator: '   ',        // default: ' / '
  unknownFallback: '?'         // default: throws on unknown characters
});

• letterSeparator: inserted between encoded letters.
• wordSeparator: inserted between encoded words.
• unknownFallback: string used when an input character is not in the Morse table. If omitted, encode will throw an error.

Decoding Options

import { decode } from 'morse-coder';

const text = decode('.... . .-.. .-.. --- / .-- --- .-. .-.. -..', {
  letterSeparator: /\s+/,      // supports string, RegExp, or string[]
  wordSeparator: ['/', '   '], // handle both slash and triple spaces
  unknownFallback: '�'         // fallback character on unknown codes
});

• letterSeparator: splitter used to group Morse tokens into letters.
• wordSeparator: splitter used to group tokens into words.
• unknownFallback: returned when a code has no matching character; omitted to throw an error instead.

Inspecting the Character Map

import { characters } from 'morse-coder';

const { letters, digits, punctuation } = characters();
console.log(letters.A); // .-

characters() returns shallow copies so you can inspect or extend them without mutating internal state.

Working with Audio

import { audio } from 'morse-coder';

const morseAudio = audio('CQ CQ', {
  inputType: 'text', // 'text' | 'morse' | 'auto' (default)
  wpm: 18,
  frequency: 700,
  sampleRate: 44100,
  volume: 0.6
});

await morseAudio.save('cq.wav');   // write to disk
await morseAudio.play();           // play through system default player
morseAudio.stop();                 // stop playback early (no resume)

const buffer = morseAudio.toBuffer(); // obtain the WAV buffer for custom handling

When inputType is set to auto, the helper will detect whether the input looks like raw Morse (containing .-/) and choose the appropriate translation path automatically.

play() relies on play-sound, which shells out to an installed player such as afplay (macOS) or mplayer (Linux/Windows). Install one of the supported players if playback fails.

TypeScript Support

The package ships with TypeScript declarations. If you need to reference the types directly:

import type { EncodeOptions, DecodeOptions, MorseAudioOptions } from 'morse-coder';

No additional configuration is required in a standard TS + ES2020 project.

Building from Source

npm run build

Outputs compiled ESM modules and .d.ts files into the dist directory. Bundlers such as Vite, webpack, and esbuild can consume the published package without additional steps.

License

MIT