Download the PHP package ryanshay/sos without Composer

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

• Features
• Installation
• Quick Start
• Detailed Usage Examples
  • Text Translation
  • Audio Generation
  • Visual Representations
  • Blinking Light Patterns
  • Govee Smart Light Control
  • Data Export
  • Error Handling
• Supported Characters
• Configuration Options
• Class Structure
• Examples Directory
• Running Tests
• Requirements
• License
• Contributing
• Author

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

• 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

Install via Composer:

Quick Start

Detailed Usage Examples

Text Translation

Audio Generation

Visual Representations

Blinking Light Patterns

Terminal Blinking

HTML/JavaScript Patterns

Govee Smart Light Control

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

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

Advanced Configuration

Device Discovery

Data Export

Error Handling

Supported Characters

Letters

A-Z (case-insensitive)

Numbers

0-9

Punctuation

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

Special

• Space (word separator in Morse: /)

File Output Configuration

Security Requirements

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

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

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

• 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

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

Govee Controller

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

Class Structure

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

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

Utility Classes

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

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

Output File Formats

Audio

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

Images

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

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

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

License

MIT License