PHPackages                             ryanshay/sos - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. ryanshay/sos

ActiveLibrary[Image & Media](/categories/media)

ryanshay/sos
============

A PHP library for translating between Natural Language and Morse code. Supports audio, visual, and blink translations.

v1.0.0(10mo ago)00MITPHPPHP >=7.4

Since Jul 18Pushed 10mo agoCompare

[ Source](https://github.com/ryanshay/sos)[ Packagist](https://packagist.org/packages/ryanshay/sos)[ Docs](https://github.com/rshay/sos)[ RSS](/packages/ryanshay-sos/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Morse Code Translator
=====================

[](#morse-code-translator)

A comprehensive PHP library for translating between text and Morse code with support for audio generation, visual representations, and blinking light patterns.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Detailed Usage Examples](#detailed-usage-examples)
    - [Text Translation](#text-translation)
    - [Audio Generation](#audio-generation)
    - [Visual Representations](#visual-representations)
    - [Blinking Light Patterns](#blinking-light-patterns)
    - [Govee Smart Light Control](#govee-smart-light-control)
    - [Data Export](#data-export)
    - [Error Handling](#error-handling)
- [Supported Characters](#supported-characters)
- [Configuration Options](#configuration-options)
- [Class Structure](#class-structure)
- [Examples Directory](#examples-directory)
- [Running Tests](#running-tests)
- [Requirements](#requirements)
- [License](#license)
- [Contributing](#contributing)
- [Author](#author)

Features
--------

[](#features)

- **Text Translation**: Convert between text and Morse code bidirectionally
- **Audio Generation**: Create WAV audio files with configurable speed and tone
- **Visual Representations**: Generate images (PNG, JPEG, GIF) and SVG files showing Morse patterns
- **Blinking Patterns**: Real-time terminal flashing and HTML/JavaScript animations
- **Smart Light Control**: Control Govee smart lights over LAN to blink Morse code patterns
- **Data Export**: Export timing data in JSON, CSV, or Arduino-compatible formats
- **Error Handling**: Comprehensive exception handling with configurable behavior
- **Character Support**: Letters (A-Z), numbers (0-9), common punctuation marks
- **Customization**: Extensive options for audio, visual, and timing parameters

Use Cases
---------

[](#use-cases)

- **Education**: Teaching Morse code with visual and audio aids
- **Emergency Signaling**: Generate SOS patterns in multiple formats including smart lights
- **Amateur Radio**: Practice tools for ham radio operators
- **Accessibility**: Alternative communication methods
- **Hardware Projects**: Arduino/Raspberry Pi integration
- **Smart Home Integration**: Control Govee lights for notifications and alerts
- **Web Applications**: Embed Morse code features in websites
- **Mobile Apps**: Backend for Morse code mobile applications
- **Historical Preservation**: Demonstrate historical communication methods

Installation
------------

[](#installation)

Install via Composer:

```
composer require ryanshay/sos
```

Quick Start
-----------

[](#quick-start)

```
use SOS\Translator\Translator;

$translator = new Translator();

// Basic translation
$morse = $translator->textToMorse('Hello World');
echo $morse; // .... . .-.. .-.. --- / .-- --- .-. .-.. -..

$text = $translator->morseToText('... --- ...');
echo $text; // SOS

// IMPORTANT: Set output directory before generating any files
$translator->setOutputDirectory('/path/to/output');
$translator->setMaxFileSize(52428800); // Optional: 50MB default
```

Detailed Usage Examples
-----------------------

[](#detailed-usage-examples)

### Text Translation

[](#text-translation)

```
use SOS\Translator\Translator;
use SOS\Translator\UnsupportedCharacterMode;

$translator = new Translator();

// Basic text to Morse
$morse = $translator->textToMorse('HELLO WORLD');
// Output: .... . .-.. .-.. --- / .-- --- .-. .-.. -..

// Morse to text
$text = $translator->morseToText('... --- ...');
// Output: SOS

// Single character lookup
$charMorse = $translator->getCharacterMorse('A');
// Output: .-

// Handle unsupported characters
$translator = new Translator(UnsupportedCharacterMode::SKIP);
$morse = $translator->textToMorse('Hello @ World'); // @ is skipped

$translator = new Translator(UnsupportedCharacterMode::REPLACE);
$morse = $translator->textToMorse('Hello @ World'); // @ replaced with ?

```

### Audio Generation

[](#audio-generation)

```
use SOS\Translator\Translator;
use SOS\Translator\AudioGenerator;

$translator = new Translator();

// REQUIRED: Set output directory first
$translator->setOutputDirectory('./output');

// Simple audio generation
$translator->generateAudioFile('SOS', 'sos.wav');

// Custom audio settings
$audioGen = new AudioGenerator();
$audioGen->setSpeed(20);        // 20 words per minute
$audioGen->setFrequency(800);   // 800 Hz tone
$audioGen->setVolume(0.7);      // 70% volume
$audioGen->setSampleRate(22050); // Lower sample rate for smaller files

$translator->generateAudioFile('HELLO WORLD', 'custom.wav', $audioGen);

// Direct Morse to audio
$morseCode = '... --- ...';
$audioGen->generateWavFile($morseCode, 'morse.wav');
```

### Visual Representations

[](#visual-representations)

```
use SOS\Translator\Translator;
use SOS\Translator\VisualGenerator;

$translator = new Translator();

// REQUIRED: Set output directory first
$translator->setOutputDirectory('./output');

// Generate PNG image
$translator->generateVisualFile('SOS', 'sos.png');

// Generate SVG (scalable)
$translator->generateVisualFile('HELLO', 'hello.svg');

// Custom visual settings
$visualGen = new VisualGenerator();
$visualGen->setDotWidth(40);           // Larger dots
$visualGen->setElementHeight(30);      // Taller elements
$visualGen->setMaxWidth(600);          // Narrower image
$visualGen->setColors(
    [255, 255, 255],  // White background
    [0, 0, 0],        // Black elements
    [128, 128, 128]   // Gray labels
);

$translator->generateVisualFile('MORSE CODE', 'custom.png', $visualGen);
```

### Blinking Light Patterns

[](#blinking-light-patterns)

#### Terminal Blinking

[](#terminal-blinking)

```
use SOS\Translator\Translator;

$translator = new Translator();

// Inline terminal blinking
$translator->blinkInTerminal('SOS');

// Fullscreen terminal flashing
$translator->blinkInTerminal('EMERGENCY', [
    'fullscreen' => true,
    'speed' => 15,      // 15 WPM
    'repeats' => 3      // Repeat 3 times
]);

// Direct control with TerminalBlinker
use SOS\Translator\TerminalBlinker;

$blinker = new TerminalBlinker();
$blinker->setSpeed(20);
$blinker->setColors("\033[41m", "\033[40m"); // Red on/off
$blinker->blinkInline('... --- ...', 'SOS');
```

#### HTML/JavaScript Patterns

[](#htmljavascript-patterns)

```
use SOS\Translator\Translator;
use SOS\Translator\BlinkPatternGenerator;

$translator = new Translator();

// REQUIRED: Set output directory first
$translator->setOutputDirectory('./output');

// Generate HTML with blinking animation
$translator->generateBlinkPattern('HELLO', 'hello.html');

// Custom HTML pattern
$blinkGen = new BlinkPatternGenerator();
$blinkGen->setSpeed(10);                    // Slow for learning
$blinkGen->setColors('#00FF00', '#000000'); // Green on black
$blinkGen->setLightSize(300);               // Large light
$blinkGen->setIncludeControls(false);       // Auto-play only

$translator->generateBlinkPattern('SOS', 'emergency.html', $blinkGen);
```

### Govee Smart Light Control

[](#govee-smart-light-control)

Control Govee smart lights over your local network to display Morse code patterns.

#### Prerequisites

[](#prerequisites)

1. Govee smart light that supports LAN control
2. Enable "LAN Control" in the Govee Home app:
    - Open Govee Home app
    - Go to your device settings
    - Enable "LAN Control" option
3. Computer and Govee device on the same network

#### Basic Usage

[](#basic-usage)

```
use SOS\Translator\Translator;
use SOS\Translator\GoveeController;

$controller = new GoveeController();

// Discover devices on the network
$devices = $controller->discoverDevices();

if (!empty($devices)) {
    // Select the first device
    $controller->selectDevice(0);

    // Or select by IP address
    // $controller->selectDeviceByIp('192.168.1.100');

    $translator = new Translator();
    $translator->blinkOnGoveeLight('SOS', $controller);
}
```

#### Advanced Configuration

[](#advanced-configuration)

```
// Configure colors (RGB values)
$controller->setColors(
    [255, 0, 0],    // Red for "on" state
    [0, 0, 0]       // Off for "off" state
);

// Set speed
$controller->setSpeed(15); // 15 WPM for emergency

// Set brightness
$controller->setBrightness(100); // Maximum brightness

// Emergency signaling example
$controller->setColors([255, 0, 0]); // Red light
$controller->setBrightness(100);
$controller->setSpeed(15);

$translator->blinkOnGoveeLight('SOS HELP', $controller);
```

#### Device Discovery

[](#device-discovery)

```
// Discover all Govee devices
$devices = $controller->discoverDevices();

foreach ($devices as $device) {
    echo "Device: " . $device['device'] . "\n";
    echo "IP: " . $device['ip'] . "\n";
    echo "Model: " . $device['sku'] . "\n";
}
```

### Data Export

[](#data-export)

```
use SOS\Translator\Translator;

$translator = new Translator();

// REQUIRED: Set output directory first
$translator->setOutputDirectory('./output');

// Export as JSON
$translator->generateBlinkPattern('TEST', 'timings.json');

// Export as CSV
$translator->generateBlinkPattern('TEST', 'timings.csv');

// Get timing array
$timings = $translator->exportBlinkTimings('SOS', 'array');
// Returns: [
//   ['state' => 'on', 'duration' => 60],
//   ['state' => 'off', 'duration' => 60],
//   ...
// ]

// Generate Arduino code
$arduinoCode = $translator->exportBlinkTimings('SOS', 'arduino');
// Returns complete Arduino sketch
```

### Error Handling

[](#error-handling)

```
use SOS\Translator\Translator;
use SOS\Translator\UnsupportedCharacterMode;
use SOS\Translator\Exceptions\InvalidCharacterException;
use SOS\Translator\Exceptions\InvalidMorseCodeException;

// Throw exceptions (default)
$translator = new Translator();
try {
    $morse = $translator->textToMorse('Hello @');
} catch (InvalidCharacterException $e) {
    echo "Invalid character: " . $e->getCharacter();
    echo " at position: " . $e->getPosition();
}

// Skip invalid characters
$translator = new Translator(UnsupportedCharacterMode::SKIP);
$morse = $translator->textToMorse('Hello @ World');
// @ is supported, but if using an unsupported character:
// Skip mode will ignore it
// Replace mode will substitute it

// Replace invalid characters
$translator = new Translator(UnsupportedCharacterMode::REPLACE);
$translator->setReplacementCharacter('?');
$morse = $translator->textToMorse('Hello ~ World');
// ~ becomes ?, result includes ..--..
```

Supported Characters
--------------------

[](#supported-characters)

### Letters

[](#letters)

A-Z (case-insensitive)

### Numbers

[](#numbers)

0-9

### Punctuation

[](#punctuation)

- Period (.)
- Comma (,)
- Question mark (?)
- Apostrophe (')
- Exclamation mark (!)
- Slash (/)
- Parentheses ()
- Ampersand (&)
- Colon (:)
- Semicolon (;)
- Equals (=)
- Plus (+)
- Minus (-)
- Underscore (\_)
- Quotation mark (")
- Dollar sign ($)
- At sign (@)

### Special

[](#special)

- Space (word separator in Morse: /)

File Output Configuration
-------------------------

[](#file-output-configuration)

### Security Requirements

[](#security-requirements)

For security reasons, all file generation methods require setting an output directory:

```
$translator = new Translator();

// REQUIRED before generating any files
$translator->setOutputDirectory('/path/to/safe/output');

// Optional: Set maximum file size (default 50MB)
$translator->setMaxFileSize(104857600); // 100MB

// Now you can generate files safely
$translator->generateAudioFile('HELLO', 'hello.wav');
$translator->generateVisualFile('HELLO', 'hello.png');
$translator->generateBlinkPattern('HELLO', 'hello.html');
```

**Security Features:**

- Path traversal protection (filenames are sanitized)
- Output directory validation (must exist and be writable)
- File size limits to prevent resource exhaustion
- All files are contained within the specified directory

Configuration Options
---------------------

[](#configuration-options)

### Audio Generator

[](#audio-generator)

- **Speed**: 5-60 WPM (words per minute)
- **Frequency**: 100-4000 Hz
- **Volume**: 0.0-1.0
- **Sample Rate**: 8000-192000 Hz

### Visual Generator

[](#visual-generator)

- **Dot Width**: 5-100 pixels
- **Element Height**: 5-100 pixels
- **Max Width**: 200+ pixels
- **Colors**: RGB arrays for background, elements, and text

### Blink Pattern Generator

[](#blink-pattern-generator)

- **Speed**: 5-60 WPM
- **Light Size**: 50-500 pixels
- **Colors**: Hex color codes
- **Controls**: Optional play/pause/speed controls

### Govee Controller

[](#govee-controller)

- **Speed**: 5-60 WPM
- **Brightness**: 1-100%
- **Colors**: RGB arrays for on/off states
- **Network**: UDP ports 4001-4003

Class Structure
---------------

[](#class-structure)

### Main Classes

[](#main-classes)

- **`Translator`** - Core translation class with integration methods

    - `textToMorse($text)` - Convert text to Morse code
    - `morseToText($morse)` - Convert Morse code to text
    - `setOutputDirectory($directory)` - Set output directory for file generation (REQUIRED)
    - `setMaxFileSize($bytes)` - Set maximum file size limit (default 50MB)
    - `generateAudioFile($text, $filename, $audioGenerator)` - Create audio file
    - `generateVisualFile($text, $filename, $visualGenerator)` - Create image/SVG
    - `blinkInTerminal($text, $options)` - Terminal flashing
    - `blinkOnGoveeLight($text, $controller)` - Control Govee smart lights
    - `generateBlinkPattern($text, $filename, $generator)` - Create HTML/data files
    - `exportBlinkTimings($text, $format)` - Export timing data
- **`AudioGenerator`** - WAV file generation

    - Configurable speed, frequency, volume, and sample rate
    - Smooth fade in/out to prevent audio clicks
- **`VisualGenerator`** - Image and SVG generation

    - Support for PNG, JPEG, GIF, and SVG formats
    - Customizable colors, sizes, and spacing
    - Automatic line wrapping
- **`TerminalBlinker`** - Terminal-based flashing

    - Inline and fullscreen modes
    - ANSI escape code support
    - Configurable colors and symbols
- **`BlinkPatternGenerator`** - HTML and data export

    - Self-contained HTML with JavaScript
    - JSON, CSV, and Arduino code export
    - Configurable appearance and controls
- **`GoveeController`** - Govee smart light control

    - Device discovery via UDP multicast
    - LAN-based control (no cloud required)
    - Configurable colors, brightness, and timing
    - Support for multiple devices

### Exception Classes

[](#exception-classes)

- **`TranslatorException`** - Base exception class
- **`InvalidCharacterException`** - Invalid character in input
- **`InvalidMorseCodeException`** - Invalid Morse code format
- **`EmptyInputException`** - Empty input provided

### Utility Classes

[](#utility-classes)

- **`UnsupportedCharacterMode`** - Constants for handling invalid characters
    - `THROW_EXCEPTION` - Throw exception (default)
    - `SKIP` - Skip invalid characters
    - `REPLACE` - Replace with configurable character

Examples Directory
------------------

[](#examples-directory)

The library includes comprehensive examples:

- `basic-usage.php` - Simple translation examples
- `audio-generation.php` - Audio file creation with various settings
- `visual-generation.php` - Image and SVG generation
- `terminal-blink.php` - Terminal flashing demonstrations
- `blink-pattern.php` - HTML pattern generation
- `emergency-signal.php` - Emergency signaling example
- `govee-morse.php` - Govee smart light control for Morse code
- `govee-discovery.php` - Discover Govee devices on the network
- `error-handling.php` - Exception handling examples
- `text-to-audio.php` - Complete text to audio workflow
- `text-to-visual.php` - Complete text to visual workflow

Running Tests
-------------

[](#running-tests)

```
composer install
vendor/bin/phpunit
```

Output File Formats
-------------------

[](#output-file-formats)

### Audio

[](#audio)

- **WAV**: 16-bit PCM, mono, configurable sample rate (8-192 kHz)

### Images

[](#images)

- **PNG**: Lossless compression, transparency support
- **JPEG**: Lossy compression, smaller file sizes
- **GIF**: Limited colors, small file sizes
- **SVG**: Vector format, infinitely scalable

### Data

[](#data)

- **HTML**: Self-contained with embedded CSS/JavaScript
- **JSON**: Structured timing data with metadata
- **CSV**: Simple tabular format for spreadsheets
- **Arduino**: Complete sketch file ready to upload

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- GD extension (for image generation)
- Terminal with ANSI escape code support (for terminal blinking)

License
-------

[](#license)

MIT License

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance54

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

305d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1098292e0fa1644b844a869d9051717bc5403016cdc57327b1f298e7fd1e03c7?d=identicon)[ryanshay](/maintainers/ryanshay)

---

Top Contributors

[![ryanshay](https://avatars.githubusercontent.com/u/1563011?v=4)](https://github.com/ryanshay "ryanshay (4 commits)")

---

Tags

audiotranslatorBlinkvisualmorseemergencysosmorse-code

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ryanshay-sos/health.svg)

```
[![Health](https://phpackages.com/badges/ryanshay-sos/health.svg)](https://phpackages.com/packages/ryanshay-sos)
```

###  Alternatives

[php-ffmpeg/php-ffmpeg

FFMpeg PHP, an Object Oriented library to communicate with AVconv / ffmpeg

5.0k21.7M165](/packages/php-ffmpeg-php-ffmpeg)[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.4k855.0k18](/packages/danog-madelineproto)[happyworm/jplayer

jPlayer allows you to create a media player with a consistent interface and experience across all browsers.

4.6k114.2k1](/packages/happyworm-jplayer)[codescale/ffmpeg-php

PHP wrapper for FFmpeg application

495270.5k1](/packages/codescale-ffmpeg-php)[char0n/ffmpeg-php

PHP wrapper for FFmpeg application

495225.1k1](/packages/char0n-ffmpeg-php)[wapmorgan/mp3info

The fastest php library to extract mp3 tags & meta information.

1481.4M7](/packages/wapmorgan-mp3info)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)