ZOSCII MQ System Documentation

1. Overview and Advantage

The World's First Truly Quantum Proof Message Queue (MQ) and Data Store when used in conjunction with ZOSCII.

ZOSCII MQ is a minimal, file-based Message Queue (MQ) designed for high-assurance, B2B asynchronous communication. It leverages the file system for durability and uses specific file naming conventions for chronological ordering and message retention. It also can provide a robust message store service.

Why Use ZOSCII MQ?

The architecture offers key advantages over traditional message brokers (like RabbitMQ or Kafka) in specific freight and logistics scenarios:

• High Durability (Disk-First): Messages are written directly to the file system. Durability is tied directly to the operating system and disk health, ensuring messages are safe immediately upon publishing.
• Asynchronous B2B Integration: It excels at decoupling systems. The Puller (replikate.php) model allows external partners to control their consumption rate and timing, minimizing your exposure to their network failures.
• Security Integration (ITS): The file-based nature is perfectly suited for integrating Information Theoretic Security (ITS) encoding, where the message payload is encoded before being written to disk, offering a higher level of data security than standard SSL/TLS alone. The server needs no knownedge of the message content.
• Simplicity and Control: There is no complex daemon, database, or broker to manage. All state is controlled via files, making it easy to audit and debug.
• Zero Knowledge: When used with an ITS encoding such as ZOSCII, there is no information available at the server. No meta data besides the queue name, date/time of storage and retention.

2. Usage for Integrators: Reading and Writing Messages

ZOSCII MQ uses a simple HTTP API (via index.php) for publishing and fetching messages, and a cron script (replikate.php) for B2B integration.

A. Publishing Messages (Writing to a Queue)

Messages are published using an HTTP GET request to the index.php endpoint.

Endpoint:

/index.php?action=publish

JSON Responses:

The main ZOSCII MQ index.php gives back it's responses as either binary data with a filename as it's Content-Disposition *, or as JSON messages in the format shown here. If possible it is always good to check the system. The error if it has a value is important. If there is no value in the error, then the result is valid. A message may be provided regardless of errors or results.

{
	"system":"ZOSCII MQ",
	"version":"1.0",
	"error":"",
	"message":"Message published.",
	"result":[]
}

* Refer to the implementation of the fetchNextMessage function within replikate.php for an example of how to handle the binary and JSON responses.

* Note: It is possible to confuse JSON messages stored in ZOSCII MQ vs those JSON messages from ZOSCII MQ itself. However it shouldn't hapen if you first check the filename from within the Content-Disposition. Checking if response.system is present and whether it is "ZOSCII MQ" will make this more robust.

Example Command (HTTP):

GET /index.php?action=publish&q=customer_b&r=30&msg=%7B%22sku%22%3A%20%22123%22%7D&n=a1b2c3d4-e5f6-4000-8000-0123456789ab

JSON Response:

{
	"system":"ZOSCII MQ",
	"version":"1.0",
	"error":"",
	"message":"Message published.",
	"result":[]
}

Filename Format:

The message is saved as a file in the queues/QUEUE_NAME/ directory with the format: YYYYMMDDHHNNSSCCCC-RRRR-GUID.bin

B. Fetching Messages (Reading from a Queue - API Pull)

Messages are fetched sequentially using the unique filename as a pointer. The consumer must track this pointer (the after parameter) to ensure guaranteed, chronological delivery.

Endpoint:

/index.php?action=fetch

Success Response:

• The consumer must store the returned filename (Content-Disposition header) as its pointer.
• The consumer must only advance the pointer after successfully processing and acting on the message content.
• The system performs no message acknowledgment (ACK). Delivery guarantee relies entirely on the consumer's proper use of the pointer (after parameter).

C. B2B Replication (Puller)

For external partners (e.g. ABC Ltd) to pull data from your (e.g. XYZ Ltd) queue, they should run a dedicated cron job on their server (e.g. ABC_LOCAL_SERVER).

Script:

replikate.php

Setup:

• The partner must install this script on their server.
• They should set up a scheduled task (cron job or Windows Scheduler) to run the script every few minutes.

Endpoint:

/replikate.php

Example Command for Queue to Queue replication (HTTP):

GET /replikate.php?url=https://SOURCESERVER/index.php&sq=SOURCEQUEUE&tq=TARGETQUEUE

The script manages the state/pointer file (replikate_state_SOURCEQUEUE.txt) automatically.

Example Command for Queue to Store replication (HTTP):

GET /replikate.php?url=https://SOURCESERVER/index.php&sq=SOURCEQUEUE

D. Storing Messages (Writing to a Data Store)

Messages are stored using an HTTP GET request to the index.php endpoint.

Endpoint:

/index.php?action=store

Example Command (HTTP):

GET /index.php?action=store&r=30&msg=%7B%22sku%22%3A%20%22123%22%7D&n=a1b2c3d4-e5f6-4000-8000-0123456789ab

JSON Response:

{
	"system":"ZOSCII MQ",
	"version":"1.0",
	"error":"",
	"message":"Message stored.",
	"result":"202511021826110000-0030-9cc1980a-1719-440a-9650-6991c9cba11d.bin"
}

Filename Format:

The message is saved as a file in the store/x/y/z/ directory with the format: YYYYMMDDHHNNSSCCCC-RRRR-GUID.bin. The file will be returned if the storing of the message is successful. You will need to note this filename for later fast retrieval.

For later retrieval of the message, you must note the response.result.

E. Retrieving Messages (Reading from a Data Store)

Messages are retrieved from the data store by using the previously returned filename. The consumer must track this filename if fast retrieval is required.

Endpoint:

/index.php?action=retrieve

Success Response:

• The consumer must read the returned filename (Content-Disposition header) to determin if the file was fetched.
• If the filename was not fetched, a JSON result may have been returned.

JSON Error Response:

{
	"system":"ZOSCII MQ",
	"version":"1.0",
	"error":"Invalid name 'x202511021826110000-0030-9cc1980a-1719-440a-9650-6991c9cba11d.bin'.",
	"message":"",
	"result":[]
}

F. Scanning Messages (Scan the Data Store for unidentified messages)

Messages are retrieved from the data store by using the previously returned filename. The consumer must track this filename if fast retrieval is required.

Endpoint:

/index.php?action=scan

Success Response:

{
	"system":"ZOSCII MQ",
	"version":"1.0",
	"error":"",
	"message":"",
	"result":[
		"202511021259550001-0005-5192e106-7a99-4418-98eb-8d4cb4c6aa3a-u.bin",
		"202511021259550001-0005-be2b00c1-9419-4661-8c1d-2219780c7980-u.bin"
	]
}

• The -u within the message name indicates the message has not yet been identified.
• Given the response array of unidentified files, you can now fetch them, identify them and flag them as identified.

G. Identify Messages

Once messages have been scanned for, then identified, they can then be flagged as identified.

Endpoint:

/index.php?action=identify

Example Command (HTTP):

GET /index.php?action=identify&names=["202511021259550001-0005-5192e106-7a99-4418-98eb-8d4cb4c6aa3a-u.bin","x202511021259550001-0005-be2b00c1-9419-4661-8c1d-2219780c7980-u.bin"]

Success Response:

{
	"system":"ZOSCII MQ",
	"version":"1.0",
	"error":"",
	"message":"Returned messages identified.",
	"result":[
		"202511021259550001-0005-5192e106-7a99-4418-98eb-8d4cb4c6aa3a.bin"
	]
}

• The messages successfully identified will be returned with the -u removed.

3. Server Setup and Maintenance (For Administrators)

A. Core Directory Structure

The system is file-based and requires a dedicated root directory:

./
|-- index.php             (HTTP API: Publish/Fetch)
|-- replikate.php         (Cron: External Puller)
|-- claireup.php          (Cron: Retention Cleanup)
|-- nonce/                (Optional nonce files go here)
|-- queues/
|   |-- customer_a/       (Queue 1)
|   |-- customer_a/locks/ (Queue 1 lock files)
|   |   |-- *.bin
|   |-- customer_b/       (Queue 2)
|   |-- customer_b/locks/ (Queue 2 lock files)
|   |   |-- *.bin
|-- states/               (State Files are here for Replicators)
|   |   |-- replikate_state_*.txt
|-- store/                (Data Store Files are here)
|-- statissa.php          (Statistics, it's better to place statissa elsewhere)

B. Critical Cron Jobs

Two cron jobs must be set up on the ZOSCII MQ server to ensure stability:

1. Message Retention Cleanup (claireup.php)

This job ensures disk space is managed by deleting expired messages based on the **RRRR** value in the filename. It processes **all queues globally**.

Cron Example:

Although it's possible to run claireup.php from a browser it is recommended to run it from cron if possible. To run it from the browser, you will first need to change the CLI_ONLY constant to FALSE from within the claireup.php file. If you do that, you are best ensure that it cannot be run by unauthorised parties if you don't want it to run.

0 0 * * * /usr/bin/php /path/to/claireup.php

4. Deployment Strategies

ZOSCII MQ supports two primary deployment patterns, each optimized for different use cases:

Strategy 1: Internal Business Message Bus

Primary Server (HQ)          Backup Server (DR Site)
   ZOSCII MQ        ─────→      ZOSCII MQ
   [All Queues]     replikate   [Mirror Copy]
                    (periodic)
    

Message Distribution Patterns

              Primary Server
                 ZOSCII MQ
          [company_announcements]
                    ↓
       ┌────────────┼────────────┬────────────┐
       ↓            ↓            ↓            ↓
    John's PC    Mary's PC    Bob's PC    ... 1,000+ PCs
    
1 message published → 1,000+ PCs all fetch from same queue
Each PC independently reads the same messages
No replication needed - standard ZOSCII MQ behavior
    

                Primary Server (HQ)
                   ZOSCII MQ
            [company_announcements]
                      ↓
          ┌───────────┴───────────┬───────────────┐
          ↓                       ↓               ↓
     replikate.php          replikate.php    replikate.php
          ↓                       ↓               ↓
    Server A (Sydney)       Server B (Tokyo)  Server C (London)
      ZOSCII MQ               ZOSCII MQ         ZOSCII MQ
          ↓                       ↓               ↓
    ┌─────┼─────┐           ┌─────┼─────┐   ┌─────┼─────┐
    ↓     ↓     ↓           ↓     ↓     ↓   ↓     ↓     ↓
  PC1   PC2  PC500       PC501 PC502 PC1000 ... PC2000 PC3000

1 message → striped to 3 regional servers → 3,000+ PCs globally
Each regional server services local PCs (lower latency)
    

Strategy 2: High Throughput AWS B2B Integration

Business A (AWS)         Business B (AWS)         Business C (AWS)
 ZOSCII MQ Docker         ZOSCII MQ Docker         ZOSCII MQ Docker
 [Push anytime]           [Push anytime]           [Push anytime]
      ↓                         ↓                         ↓
      └─────────────────────────┴─────────────────────────┘
                                 ↓
                    Head Office Server (Local)
                         ZOSCII MQ
                    [Pulls 24/7 via replikate.php]
                    [Aggregates all business data]
    

Strategy Comparison

5. Docker Deploys

Deploying ZOSCII MQ using Docker provides an **instant, persistent message queue** solution. There are three primary deployment strategies for managing the deployment environment and persistent queue data (messages and nonces):

Strategy 1: Instant Deploy (Docker Named Volumes) - Recommended for simplicity

This strategy is best for quick setup and development environments. It uses **Docker Named Volumes** which Docker automatically manages on the host machine.

Deployment Details:

• Persistence: The default docker-compose.yml uses Named Volumes (zoscii_data and zoscii_nonce).
• Location: Data is stored in a hidden, internal location managed by Docker on your host machine.
• Expansion: The storage size is dynamic and will grow automatically, limited only by the host machine's available disk space.

The volumes section in the docker-compose.yml looks like this:

volumes:
  # Data is mapped to Docker-managed volumes defined at the bottom of the file.
  - zoscii_data:/app/queues
  - zoscii_nonce:/app/nonce

volumes:
  zoscii_data:
  zoscii_nonce:

Strategy 2: Dedicated Data Path (Host Bind Mounts) - Recommended for local production

This strategy gives you full control over where the queue data resides. This is essential for environments where you need to explicitly back up, monitor, or manage the queue files using host-level tools (like rsync or specific backup agents).

Deployment Details:

• Persistence: You explicitly map a known local directory on the host to the container's data path.
• Location: Data is stored in the specific folder you choose (e.g., ./zoscii-data/).
• Control: Provides the ability to "point" the queue storage to a dedicated folder, external drive, or network file system.

The volumes section in the docker-compose.yml is modified to specify the host path:

volumes:
  # The host path (./zoscii-data) is explicitly mapped to the container path.
  - ./zoscii-data/queues:/app/queues
  - ./zoscii-data/nonce:/app/nonce

# NOTE: Named volumes are NOT defined when using Bind Mounts.

Strategy 3: Serverless Cloud Deploy (AWS Fargate/Google Cloud Run) - Recommended for zero local install

If you wish to deploy without installing Docker or running a package manager locally, the best method is a **Serverless Container Service** that manages the container's lifecycle and infrastructure.

Deployment Details:

• Zero Install: You only interact with the cloud provider's web console (AWS/Google Cloud).
• Managed Service: The cloud provider runs your container, manages the host OS, and handles auto-scaling.
• Storage Configuration: For persistence, the container's /app/queues directory must be mounted to a cloud file system service (like **AWS EFS** or **Google Cloud Filestore**) during deployment setup. This replaces the Docker volume concept with a network file system.

Once your ZOSCII MQ Docker image is pushed to a public registry (via automated build, e.g., GitHub Actions), you can deploy it in a few clicks.

6. Running the Cleanup Cron Job (claireup.php)

Since claireup.php is designed to be run from the command line (CLI), you can execute it manually inside the running container:

docker-compose exec zoscii-mq php /app/claireup.php

You can automate this by setting up a host-level cron job that calls the docker-compose exec command every minute. **Note for Strategy 3 (Cloud Deploy):** For cloud deployments, you must use the cloud provider's native scheduling tools (e.g., **AWS CloudWatch Events/EventBridge** or **Google Cloud Scheduler**) to execute the cleanup command on the running container.

6. Comparison with Traditional Message Brokers

Architecture Comparison

Performance and Scale

Security Comparison

Use Case Suitability

7. ZOSCII MQ Web Radio

ZOSCII MQ Web Radio is a JavaScript-based web radio player that consumes media from ZOSCII MQ queues. It provides a complete, embeddable radio station interface for websites, supporting multi-channel playback, queue management, and ZOSCII-encoded content.

Overview

The Web Radio system consists of two main components:

• ZOSCIIRadioPlayer - The player component that fetches and plays content from queues
• ZOSCIIMQPublisher - A publishing tool for uploading content to queues

Key Features

• ✅ Multi-channel/queue support with configurable playback behaviors
• ✅ ZOSCII-encoded content decoding (requires ROM file)
• ✅ Multi-format support: MP3 audio, JPEG images, UTF-8 text (including multilingual lyrics)
• ✅ Visual oscilloscope and progress indicators
• ✅ Play history navigation (Previous/Next track)
• ✅ ES5-compatible JavaScript (works in older browsers)
• ✅ Fully customizable styling and layout
• ✅ Zero external dependencies (except jQuery)

A. Player Implementation

Basic HTML Structure

The player requires specific HTML elements with designated class names for the JavaScript to bind to:

<div id="geZOSCIIMQPlayer" class="gsZOSCIIPlayer">
    <!-- Configuration Section -->
    <div class="geConfigSection">
        <input class="geQueueUrl" type="text" value="index.php">
        <select class="geQueueNames" multiple></select>
        <input class="geROMFile" type="file">
        <select class="geBehavior">
            <option value="repeatQueue">Repeat Channel</option>
            <option value="repeatAllQueues">Repeat All Channels</option>
            <option value="nextQueue">Next Channel</option>
            <option value="waitAtEnd">Wait at End</option>
            <option value="stopAtEnd">Stop at End</option>
            <option value="randomQueue">Random Channel</option>
        </select>
    </div>

    <!-- Control Buttons -->
    <button class="geStartButton">Connect to Channel</button>
    <button class="geStopButton">Stop</button>
    <button class="geToggleButton">Pause</button>
    <button class="gePreviousButton">Previous</button>
    <button class="geNextButton">Next</button>

    <!-- Status Display -->
    <div class="geStatus"></div>
    <div class="geNowPlaying"></div>

    <!-- Progress Visualization -->
    <div class="geProgressBar"></div>
    <div class="geOscilloscope"></div>

    <!-- Media Display -->
    <audio class="gePlayer"></audio>
    <div class="geImage"></div>
    <div class="geText"></div>
</div>

JavaScript Initialization

<script src="js/zosciiradioplayer.js"></script>
<script>
$(document).ready(function() {
    var m_strComponentID = 'geZOSCIIMQPlayer';
    
    function element(strScope, strClass) {
        return $('.' + strClass, '#' + strScope);
    }
    
    // Populate available channels
    var arrQueueNames = ['Cyborg Unicorn', 'ZOSCII'];
    var objQueueSelect = element(m_strComponentID, 'geQueueNames');
    for (var i = 0; i < arrQueueNames.length; i++) {
        objQueueSelect.append('<option selected value="' + 
            arrQueueNames[i] + '">' + arrQueueNames[i] + '</option>');
    }
    
    // Define callbacks
    function onStart() {
        // Hide config, show controls
        element(m_strComponentID, 'geConfigSection').hide();
        element(m_strComponentID, 'geStartButton').hide();
        element(m_strComponentID, 'geStopButton').show();
        element(m_strComponentID, 'geToggleButton').show();
        
        // Return selected queues to player
        return element(m_strComponentID, 'geQueueNames').val() || [];
    }
    
    function onStop() {
        // Show config, hide controls
        element(m_strComponentID, 'geConfigSection').show();
        element(m_strComponentID, 'geStartButton').show();
        element(m_strComponentID, 'geStopButton').hide();
    }
    
    // Initialize player
    var objRadioPlayer = new ZOSCIIRadioPlayer(m_strComponentID, { 
        clearImageAfterSong: true,
        clearTextAfterImage: true,
        clearTextAfterSong: true,
        imageDelay: 10,
        onStart: onStart,
        onStop: onStop
    });
});
</script>

Player Options

Playback Behaviors

B. Advanced Streaming Features

Chunked Fetch with Offset/Length

The fetch action now supports optional offset and length parameters for partial file retrieval, enabling true streaming and progressive download capabilities:

POST /index.php
Content-Type: application/x-www-form-urlencoded

action=fetch&q=music_channel&after=20251117120000.bin&offset=0&length=65536

Response Headers:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="20251117120100.bin"
Content-Length: 65536
X-ZOSCII-Offset: 0
X-ZOSCII-Total-Length: 3145728

Use Cases:

• Progressive loading of large audio files
• Bandwidth-limited streaming
• Mobile-friendly partial downloads
• Resume interrupted downloads

Note: The current Web Radio player implementation fetches complete files. The streaming infrastructure is available for custom implementations.

C. Publisher Tool

The ZOSCII MQ Publisher provides a simple interface for uploading content to queues.

HTML Structure

<div id="geZOSCIIMQPublisher" class="gsZOSCIIPublisher">
    <input class="geQueueURL" type="text" value="index.php">
    <input class="geQueueName" type="text" value="test_radio">
    <input class="geRetention" type="number" value="7">
    <input class="geROMFile" type="file">
    <input class="gePublishFile" type="file">
    <button class="gePublishFileButton">Publish File</button>
    <div class="geStatus"></div>
</div>

JavaScript Initialization

<script src="js/tozoscii.js"></script>
<script src="js/zosciipublisher.js"></script>
<script>
$(document).ready(function() {
    var objPublisher = new ZOSCIIMQPublisher('geZOSCIIMQPublisher', {});
});
</script>

Publishing Process

1. User selects ROM file (for ZOSCII encoding)
2. User selects content file (MP3, JPEG, or text)
3. User configures queue name and retention days
4. Publisher encodes file using ZOSCII ROM
5. Encoded content uploaded to queue via publish action

D. Content Type Support and Sequencing

ZOSCII MQ Web Radio supports three file types that are automatically detected and displayed appropriately. The power comes from sequencing these types in the queue to create rich multimedia experiences.

Supported File Types

1. MP3 Audio

• Automatically detected via file signature (FF FB, FF F3, or ID3 tag)
• Displays ID3v1 metadata (Title, Artist, Album, Year)
• Web Audio API oscilloscope visualization
• Progress bar with seek functionality

2. JPEG Images

• Automatically detected via signature (FF D8 FF)
• Displays for configurable duration (imageDelay option)
• Can clear text when image appears
• Automatically advances to next queue item

3. UTF-8 Text

• Full Unicode support (including emoji, CJK, Arabic, etc.)
• Proper ES5-compatible UTF-8 decoding
• HTML entity escaping for security
• Scrollable display with auto-scroll to top
• Size limit configurable via maxTextLength

Content Sequencing Use Cases

The player processes queue items sequentially, allowing you to create different listening experiences by controlling the order you publish content:

Use Case 1: Music Only

Publishing Pattern: MP3 → MP3 → MP3 → MP3

User Experience: Continuous music playback, classic radio station

Queue: "classic_rock"
├─ 001-song1.mp3
├─ 002-song2.mp3
├─ 003-song3.mp3
└─ 004-song4.mp3

Use Case 2: Images with Music

Publishing Pattern: JPEG → MP3 → JPEG → MP3 → JPEG → MP3

User Experience: Album art appears before each song, then music plays

Queue: "visual_music"
├─ 001-album-art-1.jpg      (displays 10 seconds)
├─ 002-song1.mp3            (plays until end)
├─ 003-album-art-2.jpg      (displays 10 seconds)
├─ 004-song2.mp3            (plays until end)
├─ 005-band-photo.jpg       (displays 10 seconds)
└─ 006-song3.mp3            (plays until end)

Tip: Configure clearImageAfterSong: true to remove the image when music finishes.

Use Case 3: Rich Multimedia Experience

Publishing Pattern: JPEG → TEXT → MP3 → JPEG → TEXT → MP3

User Experience: Album art, then lyrics/info, then music with lyrics visible

Queue: "lyric_radio"
├─ 001-album-cover.jpg      (displays 10 seconds)
├─ 002-lyrics.txt           (displays immediately after image)
├─ 003-song.mp3             (plays with lyrics visible)
├─ 004-next-album.jpg       (displays 10 seconds, optionally clears lyrics)
├─ 005-next-lyrics.txt      (displays immediately)
└─ 006-next-song.mp3        (plays with new lyrics visible)

Configuration Options:

• clearTextAfterImage: true - Lyrics disappear when new album art appears
• clearTextAfterImage: false - Lyrics stay visible until new text file loads
• clearTextAfterSong: true - Lyrics disappear when song ends

Example: Multilingual Lyrics Display

Text files can contain lyrics in 15+ languages simultaneously, all rendered correctly:

[Verse 1 - Pain & Suffering]
Why do we fight? (English)
为什么我们战斗？(Chinese: Why do we fight?)
¿Por qué hay dolor? (Spanish: Why is there pain?)
हम क्यों रोते हैं? (Hindi: Why do we cry?)
لماذا نعاني؟ (Arabic: Why do we suffer?)

Future Content Types

The player's architecture supports adding new content types in the future:

• Video files (MP4, WebM)
• PDF documents
• Animated GIFs
• WebVTT subtitles
• Interactive HTML content

New types can be detected via file signatures and handled with appropriate display logic in the identifyType() and dispatch functions.

E. Customization Examples

Example 1: Basic Embedded Player

Minimal player for a single radio channel (see player-raw.html):

<!-- Unstyled, functional player -->
<div id="player">
    <input class="geQueueUrl" value="https://radio.example.com/index.php">
    <textarea class="geQueueNames">my_channel</textarea>
    <input class="geROMFile" type="file">
    <button class="geStartButton">Start</button>
    <audio class="gePlayer" controls></audio>
</div>

Example 2: Fully Styled Station (player.html)

Complete radio station interface with:

• Custom branding/logo
• Hidden configuration fields (pre-configured)
• Visual progress indicators
• Drag-and-drop ROM file support
• Responsive CSS layout

Example 3: Multi-Station Aggregator

// Allow users to manage favorite stations
var arrStations = [
    { name: 'Station A', url: 'https://a.com/index.php', queues: ['music', 'talk'] },
    { name: 'Station B', url: 'https://b.com/index.php', queues: ['jazz', 'news'] }
];

// Populate station selector
// User selects station, queues auto-populate
// Player connects to selected station's URL

F. Security Considerations

1. XSS Protection

All user-generated content is properly escaped:

• Text content uses htmlEncode() function
• ID3 tags sanitized before display
• Filenames validated and escaped

2. CORS Configuration

For cross-origin radio players, configure the MQ server:

# Apache .htaccess
Header set Access-Control-Allow-Origin "https://yourradio.com"
Header set Access-Control-Allow-Methods "POST, GET, OPTIONS"
Header set Access-Control-Allow-Headers "Content-Type"

3. ROM File Security

ROM files are processed client-side and never uploaded to the server, protecting the encryption key.

G. Deployment Scenarios

Scenario 1: Personal Radio Station

• Single queue: "my_radio"
• Publisher uploads MP3s with images/lyrics
• Player embedded on personal website
• Friends connect with shared ROM file

Scenario 2: Multi-Channel Web Radio

• Multiple queues: "Rock", "Jazz", "Talk Shows"
• Users select channels from dropdown
• Each channel has its own content stream
• Behavior: repeatAllQueues for continuous playback

Scenario 3: Event Streaming

• Live event queue updated in real-time
• Behavior: waitAtEnd (checks for new content every 30s)
• Images show speaker slides
• Text displays presentation notes

Scenario 4: Podcast Distribution

• Episode queue with sequential content
• Behavior: stopAtEnd (user manually advances)
• Previous/Next buttons for episode navigation
• Episode metadata in ID3 tags

H. Integration with Existing Web Infrastructure

WordPress Integration

<!-- In WordPress post/page -->
<div id="radio"></div>
<script src="/wp-content/themes/mytheme/js/zosciiradioplayer.js"></script>
<script>
// Initialize player with WordPress theme styling
</script>

Static Site Generators

• Jekyll, Hugo, Next.js: Include player HTML in template
• Configure queue URLs in site config
• Style with site's existing CSS framework

I. Live Demo

Cyborg Unicorn Radio: cyborgunicorn.com.au/radio

Features:

• Two channels: "Cyborg Unicorn" and "ZOSCII"
• Multilingual content support
• Album art display
• Lyrics synchronized with music
• Custom branding and styling

J. Browser Compatibility

Note: ES5 compatibility ensures the player works on older browsers. Web Audio API features (oscilloscope) gracefully degrade on unsupported browsers.

K. Replication and Distribution Strategies

Web Radio Replication with replikate.php

ZOSCII MQ Web Radio supports the same federated replication model as standard ZOSCII MQ queues. Any radio station can replicate content from another station's queue using replikate.php:

// Station B replicates from Station A's radio queue
GET /replikate.php?url=https://stationA.com/index.php&sq=music_channel&tq=replicated_music

Architectural Principle: The system is intentionally designed so that you cannot prevent replication without preventing playback. If someone can listen to your station, they can replicate it. This fundamental design choice enables the democratized, federated network model while forcing content creators to use ROM-based access control rather than technical restrictions.

This enables:

• Regional mirrors of popular stations (reduce latency)
• Backup/archive of radio content
• Content aggregation (pull from multiple sources into one queue)
• Load distribution across geographic locations
• Content collection and hoarding

ROM-Based Access Control

The ROM file serves as both an encoding key and an access control mechanism for radio channels. This enables two distinct distribution models:

Private Channels (Controlled Distribution)

Use Case: Monetization, subscriber-only content, or restricted distribution

Strategy:

• Publisher encodes content with a custom, private ROM file
• Only users with the exact ROM file can decode and play the content
• ROM distributed through controlled channels (payment, subscription, membership)
• Even if queue is publicly replicated, content remains unplayable without ROM

Example Scenarios:

• Subscription Radio: Monthly subscribers receive ROM file via email
• Premium Content: Paid albums encoded with unique ROMs per customer
• Corporate Radio: Internal company radio with ROM distributed only to employees
• Artist Direct Sales: Musicians sell ROM files for exclusive content access

Access Control: ZOSCII provides Information Theoretic Security (ITS) - the world's first practical implementation that is mathematically more secure than traditional encryption and dramatically faster to decode. The encoded content is mathematically unbreakable without the ROM. However, this doesn't prevent piracy - someone can share the ROM file just as easily as sharing the content itself. The protection comes from controlling who has the ROM, not from making the content uncrackable. For monetization, you must manage ROM distribution carefully (subscriptions, unique ROMs per customer, legal agreements, etc.).

Public Channels (Open Distribution)

Use Case: Maximum reach, democratized radio, community content

Strategy:

• Publisher encodes content with the official Cyborg Unicorn Logo ROM (provided with the player)
• Anyone with the player has the standard ROM and can decode/play content
• Content freely replicable across the entire network
• Creates a truly democratized, open radio network

Benefits:

• Zero Barrier to Entry: Users download player once, access all public stations
• Network Effect: More stations = more value for all users
• Viral Distribution: Content spreads organically via replication
• Censorship Resistant: Decentralized mirrors make takedowns difficult

Recommendation: If you want your radio station to be part of a global, open network where anyone can listen and stations can freely replicate each other's content, use the official Cyborg Unicorn Logo ROM file included with the ZOSCII MQ Web Radio Player distribution.

Hybrid Strategy

Stations can operate both public and private channels simultaneously:

Station Configuration:
├─ Public Queue: "free_music"          (Cyborg Unicorn ROM - open access)
├─ Premium Queue: "exclusive_content"  (Custom ROM - paid subscribers)
└─ Archive Queue: "classics"           (Cyborg Unicorn ROM - open access)

This allows monetization of premium content while building audience with free content.

Replication Network Example

            Station A (Origin - Australia)
                 Queue: "aussie_rock"
              [Cyborg Unicorn ROM]
                        │
         ┌──────────────┼──────────────┐
         │              │              │
         ▼              ▼              ▼
    Station B      Station C      Station D
    (US Mirror)   (EU Mirror)   (Asia Mirror)
    replikate     replikate     replikate
         │              │              │
         ▼              ▼              ▼
   500 US users   300 EU users   200 Asia users

Result: 1,000 users globally accessing content with regional low-latency, all using the same public ROM. Station A publishes once, content distributed worldwide automatically.

ROM Distribution Best Practices

L. Performance Characteristics

Federated Architecture Advantage

ZOSCII MQ's replikate.php enables a unique federated architecture:

Company A (Sydney)     Company B (Tokyo)      Company C (London)
    ZOSCII MQ    ←──→    ZOSCII MQ    ←──→    ZOSCII MQ
         ↓                    ↓                     ↓
   [Own Control]        [Own Control]         [Own Control]
   [Own Security]       [Own Security]        [Own Security]
   [Own Data]           [Own Data]            [Own Data]

Each node operates independently - no central point of failure, no shared infrastructure, perfect for B2B logistics and freight forwarding where different organizations need to maintain sovereignty over their systems.

Total Cost of Ownership (TCO)