# signal:// ASCII — Full Reference (v0.1.1)

signal:// converts images and video into ASCII / ANSI art. This document is the
complete machine-readable reference for agents and automations.

## Architecture
- Isomorphic engine (lib/ascii.ts): identical pixel math runs in the browser and
  on the server, so streamed frames and API renders are pixel-consistent.
- Browser studio: real-time video/webcam streaming, entirely client-side.
- A2V handoff: real-time ASCII frames can be streamed to https://a2v.platphormnews.com
  by fixed-origin window.postMessage. The raw webcam/video stream stays local.
- HTTP API: stateless single-image rendering via sharp for server-side decode.
- MCP server: exposes rendering as a JSON-RPC tool for AI agents.

## Signal math (under the hood)
1. Linear-light luminance: sRGB channels are linearized (inverse gamma), combined
   with Rec.709 weights (0.2126 R, 0.7152 G, 0.0722 B), then re-encoded. This is
   perceptually correct, unlike naive (R+G+B)/3 averaging.
2. Gamma control: an additional perceptual midtone exponent for artistic tuning.
3. High-quality downscaling: source frames are area-averaged down through an
   intermediate 2x pyramid step with high-quality smoothing, avoiding the
   aliasing and shimmer of a single hard resize.
4. Unsharp-mask sharpening: a 3x3 box-blurred copy is subtracted from the signal
   (out = in + amount * (in - blur)) to restore fine detail — hair, text and
   textures — lost during downscaling.
5. Auto-levels: a luminance histogram is built and low/high percentiles (rather
   than absolute min/max, for outlier robustness) define a black/white point;
   the tonal range is stretched between them and blended by the autoLevels
   amount, so dark or washed-out footage always maps to the full glyph ramp.
6. Floyd–Steinberg dithering: quantization error is diffused to neighbors
   (7/16 right, 3/16 down-left, 5/16 down, 1/16 down-right) recovering gradient
   detail that a hard glyph threshold would crush.
7. Sobel edge detection: 3x3 Gx/Gy convolution yields gradient magnitude and
   orientation; orientation is mapped to directional glyphs (- / | \) for line art.
8. Adaptive recursive Bayesian temporal filter (studio streaming only):
   each cell maintains a running estimate; the Kalman-style gain adapts per-cell to
   observed motion, heavily denoising static regions while staying instantly
   responsive to movement. This is what makes the stream stable instead of noisy.
9. Auto Director quality rubric: measures source percentiles, dynamic range,
   clipping, detail density, and a documented noise proxy; refines bounded tone
   and detail settings for at most three rounds and reports target_met or
   best_effort with the effective settings.
10. Rate-distortion glyph selection: selects the smallest ordered one-byte
    ASCII codebook whose measured normalized luminance RMSE is below the chosen
    ceiling. Processing evidence includes codebook size, RMSE, and entropy.
11. Compact chroma: json-compact and browser handoffs use exact rgb24-b64-v1
    per-cell RGB, matching ascii.platphormnews.com and deascii.platphormnews.com.

## Endpoints

### GET /api/health
Returns service status, version, and capability flags.
https://v2a.platphormnews.com/api/health

### POST /api/v1/render
Convert a single image. Three ways to supply the image:
- multipart/form-data with an `image` file field
- JSON body { "imageUrl": "https://..." } for a trusted or explicitly allowlisted host
- JSON body { "imageBase64": "<base64 or data URL>" }
Params may be given as query string, form fields, or JSON keys.
The endpoint accepts W3C trace context and returns trace response headers. When
server-side platform auth is configured, V2A exports resolution, rendering,
measured quality evidence, and completion without storing image bytes.
Max upload: 12582912 bytes. Columns: 8–400.
Remote URLs must use HTTPS and are checked against the trusted hostname
allowlist, public DNS addresses, three-redirect limit, image content type,
response size, and fetch timeout. Configure external hosts with
V2A_IMAGE_FETCH_ALLOWLIST.

### POST /api/mcp
Model Context Protocol over JSON-RPC 2.0. Methods: initialize, ping, tools/list,
tools/call, resources/list, resources/read, prompts/list, and prompts/get.
Tool: render_ascii (returns text; set color/format for richer output).
Single and bounded-batch tool executions export canonical MCP tool identity,
call IDs, measured evidence, and completion after public-safe redaction.

### GET /api/openapi.json
OpenAPI 3.1 specification.

### GET /api/v1/a2v-handoff
Public-safe V2A -> A2V integration manifest. The trusted receiver is
https://a2v.platphormnews.com. Launch URL:
https://a2v.platphormnews.com/?handoff=v2a&protocol=platphorm.v2a.a2v.handoff.v1&mode=webcam-stream&source=v2a.platphormnews.com&traceId=TRACE_ID

Message transport: window.postMessage to targetOrigin https://a2v.platphormnews.com.
Frame messages use type platphorm:v2a:ascii-frame and protocol
platphorm.v2a.a2v.handoff.v1. Backend async status checks use PLATPHORM_API_KEY when
configured. No PLATPHORM_API_KEY, cookies, raw video frames, audio, or camera
tracks are transferred to the browser handoff payload.

### GET /api/v1/interoperability
Returns repository-verified ASCII/deASCII/V2A/A2V API, MCP, interchange, and
fixed-origin handoff contracts. It explicitly does not claim live downstream
success; browser connected states require receiver acknowledgements.

## Parameters

### columns
- type: integer 8–400
- default: 120
- Output width in characters.

### charset
- type: enum
- default: detailed
- One of: standard, detailed, blocks, binary, dots, minimal.

### format
- type: enum
- default: text
- text | ansi | html | json | json-compact | svg.

### color
- type: boolean
- default: false
- Per-cell 24-bit color (ignored by plain text).

### invert
- type: boolean
- default: false
- Invert luminance mapping.

### contrast
- type: float 0.2–4
- default: 1.15
- Tonal contrast multiplier.

### brightness
- type: float -150–150
- default: 0
- Luminance offset.

### saturation
- type: float 0–4
- default: 1.4
- Color-mode saturation boost.

### gamma
- type: float 0.2–3
- default: 1
- Perceptual midtone response.

### edges
- type: boolean
- default: false
- Sobel edge-detection line-art mode.

### edgeStrength
- type: float 0.1–5
- default: 1.8
- Edge magnitude multiplier.

### dither
- type: boolean
- default: false
- Floyd–Steinberg error diffusion.

### sharpen
- type: float 0–1
- default: 0.35
- Unsharp-mask detail enhancement.

### autoLevels
- type: float 0–1
- default: 0.9
- Automatic percentile histogram stretch.

### structure
- type: float 0–1
- default: 0.55
- Contour-aware directional glyph substitution ( - / | \ ).

### denoise
- type: float 0–1
- default: 0.35
- Edge-preserving bilateral denoising before detail recovery.

### motionSensitivity
- type: float 0–1
- default: 0.7
- Motion responsiveness in the final Bayesian posterior update.

### autoOptimize
- type: float 0–1
- default: 0.9
- Strength of source-aware Auto Director tuning against the selected quality rubric.

### qualityTarget
- type: enum
- default: balanced
- balanced | portrait | motion | low-light | round-trip.

### glyphStrategy
- type: enum
- default: adaptive
- adaptive chooses the smallest glyph codebook under maxGlyphRmse; fixed preserves the selected ramp.

### maxGlyphRmse
- type: float 0.005–0.1
- default: 0.03
- Maximum normalized luminance quantization RMSE for adaptive glyph selection.

### monoColor
- type: hex
- default: #e5e5e5
- Color for mono/ansi/svg/html output.

## Character sets
- standard: " .:-=+*#%@" (10 levels)
- detailed: " .'`^",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$" (69 levels)
- blocks: " ░▒▓█" (5 levels)
- binary: " 01" (3 levels)
- dots: " ·•●" (4 levels)
- minimal: " .oO@" (5 levels)

## Output formats
- text -> text/plain (.txt): Plain text
- ansi -> text/plain (.ans): ANSI (truecolor)
- html -> text/html (.html): HTML
- json -> application/json (.json): JSON
- json-compact -> application/json (.json): Compact JSON + chroma
- svg -> image/svg+xml (.svg): SVG

## Defaults
{
  "columns": 120,
  "charset": "detailed",
  "format": "text",
  "color": false,
  "invert": false,
  "contrast": 1.15,
  "brightness": 0,
  "saturation": 1.4,
  "gamma": 1,
  "edges": false,
  "edgeStrength": 1.8,
  "dither": false,
  "sharpen": 0.35,
  "autoLevels": 0.9,
  "structure": 0.55,
  "denoise": 0.35,
  "motionSensitivity": 0.7,
  "autoOptimize": 0.9,
  "qualityTarget": "balanced",
  "glyphStrategy": "adaptive",
  "maxGlyphRmse": 0.03,
  "monoColor": "#e5e5e5"
}

## Examples

# Plain text
curl -F "image=@photo.jpg" "https://v2a.platphormnews.com/api/v1/render?columns=120"

# 24-bit color ANSI (paste into a truecolor terminal)
curl -F "image=@photo.jpg" "https://v2a.platphormnews.com/api/v1/render?columns=120&format=ansi&color=true"

# Standalone HTML from a remote URL
curl -X POST https://v2a.platphormnews.com/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://asciicast.stream/test-portrait.png","columns":160,"format":"html","color":true}'

# JSON (grid + per-cell color) for programmatic use
curl -X POST https://v2a.platphormnews.com/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{"imageBase64":"data:image/png;base64,iVBOR...","format":"json"}'

# MCP tool call
curl -X POST https://v2a.platphormnews.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"render_ascii","arguments":{"imageUrl":"https://asciicast.stream/test-portrait.png","columns":100,"color":true,"format":"ansi"}}}'