ARIA

HomePod Voice System

ARIA's "Speak to HomePod" feature enables Claude to announce messages through Apple HomePod speakers using a queue-based relay architecture. The system bridges ARIA's cloud services with local Apple hardware through a Mac relay daemon, leveraging pyatv's RAOP (Remote Audio Output Protocol) implementation to stream synthesized speech via AirPlay.

The relay pattern is shared with ARIA's iMessage and Apple TV integrations: tool call → Tempo job → database queue → Mac relay polls → local execution → completion callback.

File Map Across Repositories

homepod_queue Table (Migration 041)

CREATE TABLE homepod_queue (
  id         SERIAL PRIMARY KEY,
  message    TEXT NOT NULL,
  target     TEXT,             -- HomePod name; NULL = all
  status     TEXT NOT NULL DEFAULT 'pending'
             CHECK (status IN (
               'pending', 'claimed',
               'sent', 'failed'
             )),
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  claimed_at TIMESTAMPTZ,
  sent_at    TIMESTAMPTZ,
  error      TEXT
);

Status Lifecycle

Stale Claim Recovery

The pending endpoint automatically resets claimed rows older than 2 minutes back to pending on each poll. This handles relay crashes, network interruptions, or pyatv timeouts without manual intervention.

speak-homepod.ts

The Tempo handler is deliberately minimal. Its only job is to bridge the Tempo job system to the relay queue, keeping the hot path fast:

async function handleSpeakHomepod(pool, payload) {
  const { message, target } = payload;

  // Insert into relay queue
  const result = await pool.query(
    `INSERT INTO homepod_queue (message, target)
     VALUES ($1, $2) RETURNING id`,
    [message, target || null]
  );

  // Log to event_log for observability
  await logEvent(pool, {
    component: 'homepod',
    category: 'interaction',
    action: `HomePod announce queued`
      + (target ? ` to ${target}` : '')
      + `: "${message.slice(0, 80)}"`
  });

  return { queued: true, queue_id: result.rows[0].id };
}

Message text is truncated to 80 characters in the event log to keep observability data manageable. The full message is preserved in the homepod_queue row.

Monitoring & Debugging

The HomePod system is observable at three levels:

-- Delivery latency for last 24 hours
SELECT
  AVG(EXTRACT(EPOCH FROM sent_at - created_at)) AS avg_seconds,
  COUNT(*) FILTER (WHERE status = 'sent') AS delivered,
  COUNT(*) FILTER (WHERE status = 'failed') AS failed
FROM homepod_queue
WHERE created_at > NOW() - INTERVAL '24 hours';

Phase 1 Constraints

Phase 1: pyatv + macOS say

Current implementation. Queue-based relay with macOS native TTS and pyatv RAOP streaming. Functional for basic announcements with Siri voice.

ARIA HomePod Voice System • Technical Documentation • March 2026
Generated from source code analysis across aria, aria-tempo, aria-tempo-client, and aria-ios repositories