AWS.Polly reference

DescribeVoices

Source: src/AWS/Polly/DescribeVoices.ts

Runtime binding for polly:DescribeVoices — list the voices available for speech synthesis, optionally filtered by engine or language.

Polly voices are account-wide, so the binding takes no arguments and grants the function polly:DescribeVoices. Provide the implementation with Effect.provide(AWS.Polly.DescribeVoicesHttp).

DescribeVoices: Discovering Voices

// init
const describeVoices = yield* AWS.Polly.DescribeVoices();

// runtime
const result = yield* describeVoices({ LanguageCode: "en-US" });
const voiceIds = (result.Voices ?? []).map((voice) => voice.Id);

GetLexicon

Source: src/AWS/Polly/GetLexicon.ts

Runtime binding for polly:GetLexicon — read the PLS content and attributes of a pronunciation lexicon at runtime.

Bind it to a Lexicon resource; the deploy-time half grants polly:GetLexicon scoped to that lexicon’s ARN and the runtime callable injects the lexicon name. The returned Lexicon.Content is Redacted (distilled models it as sensitive) — unwrap with Redacted.value(...) at the point of use. Provide the implementation with Effect.provide(AWS.Polly.GetLexiconHttp).

GetLexicon: Managing Lexicons

// init
const getLexicon = yield* AWS.Polly.GetLexicon(lexicon);

// runtime
const result = yield* getLexicon();
const content = result.Lexicon?.Content;
const xml =
  content === undefined
    ? undefined
    : Redacted.isRedacted(content)
      ? Redacted.value(content)
      : content;

GetSpeechSynthesisTask

Source: src/AWS/Polly/GetSpeechSynthesisTask.ts

Runtime binding for polly:GetSpeechSynthesisTask — retrieve the status (and output S3 URI) of an asynchronous synthesis task by its TaskId.

The binding takes no arguments and grants the function polly:GetSpeechSynthesisTask. Provide the implementation with Effect.provide(AWS.Polly.GetSpeechSynthesisTaskHttp).

GetSpeechSynthesisTask: Asynchronous Synthesis

// init
const getSpeechSynthesisTask = yield* AWS.Polly.GetSpeechSynthesisTask();

// runtime — bounded poll until the task leaves the queue
const task = yield* getSpeechSynthesisTask({ TaskId: taskId }).pipe(
  Effect.repeat({
    schedule: Schedule.spaced("2 seconds"),
    until: (r): boolean =>
      r.SynthesisTask?.TaskStatus === "completed" ||
      r.SynthesisTask?.TaskStatus === "failed",
    times: 25,
  }),
);

Lexicon

Source: src/AWS/Polly/Lexicon.ts

An Amazon Polly pronunciation lexicon — a W3C PLS document stored in a region that customizes how SynthesizeSpeech pronounces specific words. Identity is the region-scoped lexiconName; the PLS content is updatable in place.

Lexicon: Managing Lexicons

Store a pronunciation lexicon

const lexicon = yield* AWS.Polly.Lexicon("Acronyms", {
  lexiconName: "acronyms",
  content: `<?xml version="1.0" encoding="UTF-8"?>
<lexicon version="1.0" xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
         alphabet="ipa" xml:lang="en-US">
  <lexeme><grapheme>W3C</grapheme><alias>World Wide Web Consortium</alias></lexeme>
</lexicon>`,
});

Synthesize speech with the lexicon applied

const synthesizeSpeech = yield* AWS.Polly.SynthesizeSpeech();
const result = yield* synthesizeSpeech({
  OutputFormat: "mp3",
  VoiceId: "Joanna",
  Text: "The W3C maintains the PLS standard.",
  LexiconNames: [lexicon.lexiconName],
});

ListLexicons

Source: src/AWS/Polly/ListLexicons.ts

Runtime binding for polly:ListLexicons — list the pronunciation lexicons stored in the region (name plus attributes; use the names as LexiconNames in synthesis requests).

The binding takes no arguments and grants the function polly:ListLexicons. Provide the implementation with Effect.provide(AWS.Polly.ListLexiconsHttp).

ListLexicons: Managing Lexicons

// init
const listLexicons = yield* AWS.Polly.ListLexicons();

// runtime
const result = yield* listLexicons();
const names = (result.Lexicons ?? []).map((lexicon) => lexicon.Name);

ListSpeechSynthesisTasks

Source: src/AWS/Polly/ListSpeechSynthesisTasks.ts

Runtime binding for polly:ListSpeechSynthesisTasks — list asynchronous synthesis tasks ordered by creation date, optionally filtered by status.

The binding takes no arguments and grants the function polly:ListSpeechSynthesisTasks. Provide the implementation with Effect.provide(AWS.Polly.ListSpeechSynthesisTasksHttp).

ListSpeechSynthesisTasks: Asynchronous Synthesis

// init
const listSpeechSynthesisTasks = yield* AWS.Polly.ListSpeechSynthesisTasks();

// runtime
const result = yield* listSpeechSynthesisTasks({
  Status: "completed",
  MaxResults: 10,
});
const taskIds = (result.SynthesisTasks ?? []).map((task) => task.TaskId);

StartSpeechSynthesisStream

Source: src/AWS/Polly/StartSpeechSynthesisStream.ts

Runtime binding for polly:StartSpeechSynthesisStream — bidirectional streaming synthesis: send text incrementally as TextEvents on the input ActionStream and receive AudioEvent chunks on the output EventStream as they become available.

The binding takes no arguments and grants the function polly:StartSpeechSynthesisStream. Provide the implementation with Effect.provide(AWS.Polly.StartSpeechSynthesisStreamHttp).

NOTE: the distilled HTTP transport does not yet support bidirectional (input) event-stream request bodies — a live call currently hangs waiting for response headers (probed 2026-07; same transport gap leaves transcribe-streaming and lex StartConversation unbound). Prefer SynthesizeSpeech (request-response) until distilled core ships event-stream request support.

StartSpeechSynthesisStream: Streaming Synthesis

// init
const startSpeechSynthesisStream =
  yield* AWS.Polly.StartSpeechSynthesisStream();

// runtime
const result = yield* startSpeechSynthesisStream({
  Engine: "generative",
  OutputFormat: "mp3",
  VoiceId: "Matthew",
  ActionStream: Stream.make(
    { TextEvent: { Text: "Hello from Alchemy." } },
    { CloseStreamEvent: {} },
  ),
});
const events = yield* Stream.runCollect(result.EventStream!);
const audioBytes = Array.from(events)
  .flatMap((event) => (event.AudioEvent?.AudioChunk ? [event.AudioEvent.AudioChunk] : []))
  .reduce((total, chunk) => total + chunk.length, 0);

StartSpeechSynthesisTask

Source: src/AWS/Polly/StartSpeechSynthesisTask.ts

Runtime binding for polly:StartSpeechSynthesisTask — start an asynchronous synthesis task that writes the audio (or speech marks) to an S3 bucket, for texts too long for the synchronous SynthesizeSpeech.

The binding grants polly:StartSpeechSynthesisTask. Polly writes the output with the caller’s credentials, so the function also needs s3:PutObject on the output bucket — compose with AWS.S3.PutObject(bucket). Provide the implementation with Effect.provide(AWS.Polly.StartSpeechSynthesisTaskHttp).

StartSpeechSynthesisTask: Asynchronous Synthesis

// init — the S3 PutObject binding grants Polly's output write
yield* AWS.S3.PutObject(bucket);
const startSpeechSynthesisTask = yield* AWS.Polly.StartSpeechSynthesisTask();

// runtime
const started = yield* startSpeechSynthesisTask({
  OutputFormat: "mp3",
  OutputS3BucketName: "my-audio-bucket",
  VoiceId: "Joanna",
  Text: longArticleText,
});
const taskId = started.SynthesisTask?.TaskId;

SynthesizeSpeech

Source: src/AWS/Polly/SynthesizeSpeech.ts

Runtime binding for polly:SynthesizeSpeech — synthesize UTF-8 plain text or SSML into a stream of audio bytes.

Polly is a pure pay-per-call service with no resource to manage: the binding takes no arguments and grants the function polly:SynthesizeSpeech. The response AudioStream is a byte Stream of the encoded audio (raw distilled types, no marshalling). Provide the implementation with Effect.provide(AWS.Polly.SynthesizeSpeechHttp).

SynthesizeSpeech: Synthesizing Speech

// init
const synthesizeSpeech = yield* AWS.Polly.SynthesizeSpeech();

// runtime — AudioStream is a byte Stream of the encoded audio
const result = yield* synthesizeSpeech({
  Engine: "neural",
  OutputFormat: "mp3",
  VoiceId: "Joanna",
  Text: "Hello from Alchemy.",
});
const chunks = yield* Stream.runCollect(result.AudioStream!);