Command

New-ImageConsoleStory

Module: ImagePlayground
Inputs: ChartForgeX.Terminal.TerminalStory ImagePlayground.PowerShell.ImageConsoleStoryStep[] System.String
Outputs: ChartForgeX.Terminal.TerminalStory

Creates a reusable script-free console story from PowerShell-native steps, captured transcript lines, or a native ChartForgeX terminal story.

Syntax

New-ImageConsoleStory
[-AnimationScale <Int32>]
[-EndHoldSeconds <Double>]
[-FilePath <String>]
[-FramesPerSecond <Int32>]
[-MaximumFrames <Int32>]
[-NoLoop]
[-PassThru]
[-Show]
[-StoryScript] <ScriptBlock>
[<CommonParameters>]

Parameter set: StoryScript

New-ImageConsoleStory
[-AnimationScale <Int32>]
-Content <ScriptBlock>
[-CustomPrompt <String>]
[-Dialect <TerminalDialect>]
[-EndHoldSeconds <Double>]
[-FilePath <String>]
[-FontSize <Double>]
[-FramesPerSecond <Int32>]
[-InitialDelaySeconds <Double>]
[-LineDelaySeconds <Double>]
[-LineHeight <Double>]
[-MaximumFrames <Int32>]
[-NoFinalPrompt]
[-NoLoop]
[-Palette <TerminalTheme>]
[-PassThru]
[-PngOutputScale <Int32>]
[-Show]
[-Speed <Slow|Normal|Fast>]
[-TabHoldSeconds <Double>]
[-Theme <String>]
[-Title <String>]
[-TypingSpeed <Double>]
[-Width <Int32>]
[-WindowStyle <MacOS|WindowsTerminal|Minimal>]
[-WorkingDirectory <String>]
[<CommonParameters>]

Parameter set: Content

New-ImageConsoleStory
[-AnimationScale <Int32>]
[-CustomPrompt <String>]
[-Dialect <TerminalDialect>]
[-EndHoldSeconds <Double>]
[-FilePath <String>]
[-FontSize <Double>]
[-FramesPerSecond <Int32>]
[-InitialDelaySeconds <Double>]
[-LineDelaySeconds <Double>]
[-LineHeight <Double>]
[-MaximumFrames <Int32>]
[-NoFinalPrompt]
[-NoLoop]
[-Palette <TerminalTheme>]
[-PassThru]
[-PngOutputScale <Int32>]
[-Show]
[-Speed <Slow|Normal|Fast>]
-Step <ImageConsoleStoryStep[]>
[-TabHoldSeconds <Double>]
[-Theme <String>]
[-Title <String>]
[-TypingSpeed <Double>]
[-Width <Int32>]
[-WindowStyle <MacOS|WindowsTerminal|Minimal>]
[-WorkingDirectory <String>]
[<CommonParameters>]

Parameter set: Step

New-ImageConsoleStory
[-AnimationScale <Int32>]
[-EndHoldSeconds <Double>]
[-FilePath <String>]
[-FramesPerSecond <Int32>]
[-MaximumFrames <Int32>]
[-NoLoop]
[-PassThru]
[-Show]
-Story <TerminalStory>
[<CommonParameters>]

Parameter set: Story

New-ImageConsoleStory
[-AnimationScale <Int32>]
-CommandText <String>
[-CustomPrompt <String>]
[-Dialect <TerminalDialect>]
[-EndHoldSeconds <Double>]
[-FilePath <String>]
[-FontSize <Double>]
[-FramesPerSecond <Int32>]
[-InitialDelaySeconds <Double>]
-InputObject <String>
[-LineDelaySeconds <Double>]
[-LineHeight <Double>]
[-MaximumFrames <Int32>]
[-NoFinalPrompt]
[-NoLoop]
[-Palette <TerminalTheme>]
[-PassThru]
[-PngOutputScale <Int32>]
[-Show]
[-Speed <Slow|Normal|Fast>]
[-TabHoldSeconds <Double>]
[-Theme <String>]
[-Title <String>]
[-TypingSpeed <Double>]
[-Width <Int32>]
[-WindowStyle <MacOS|WindowsTerminal|Minimal>]
[-WorkingDirectory <String>]
[<CommonParameters>]

Parameter set: Transcript

Description

The recommended Content and Step parameter sets compose objects created by the New-ImageConsoleStoryCommand, Output, Table, BlankLine, Pause, Tab, and Select-ImageConsoleStoryTab cmdlets. StoryScript remains available as the low-level ChartForgeX builder escape hatch.

The cmdlet renders deterministic SVG or HTML motion, animated GIF or APNG motion, and a completed PNG state. It never executes the displayed command: callers run scripts themselves and pipe captured output when they want a real execution transcript.

Examples

Author a paced multi-tab Windows Terminal presentation

$story = New-ImageConsoleStory -WindowStyle WindowsTerminal -Width 1100 -Speed Slow -Content {
  New-ImageConsoleStoryTab -Id PowerShell -Title 'PowerShell' -Profile PowerShell -Active
  New-ImageConsoleStoryCommand -Text 'dotnet build'
  New-ImageConsoleStoryOutput -Text 'Build succeeded.' -Style Success

  New-ImageConsoleStoryTab -Id WindowsPowerShell -Title 'Windows PowerShell' -Profile WindowsPowerShell
  New-ImageConsoleStoryCommand -Text '.\Invoke-LegacyTests.ps1'
  New-ImageConsoleStoryOutput -Text 'PS 5.1 compatibility passed.' -Style Success

  New-ImageConsoleStoryTab -Id Ubuntu -Title 'Ubuntu' -Profile Ubuntu
  New-ImageConsoleStoryCommand -Text './build.sh'
  New-ImageConsoleStoryOutput -Text 'Linux package ready.' -Style Success
}
$story | Export-ImageConsoleStory -Path '.\demo.gif'

Creates three persistent tab buffers. Each new tab opens atomically after the previous tab's reading dwell, then the shared story is exported through Export-ImageConsoleStory.

Jump between retained sessions intentionally

$story = New-ImageConsoleStory -WindowStyle WindowsTerminal -Speed Slow -Content {
  New-ImageConsoleStoryTab -Id PowerShell -Profile PowerShell -Active
  New-ImageConsoleStoryTab -Id Logs -Title 'Build logs' -Profile PowerShell -Background
  New-ImageConsoleStoryCommand -Text 'dotnet build'
  Select-ImageConsoleStoryTab -Id Logs
  New-ImageConsoleStoryOutput -Text 'Waiting for integration tests...' -Style Muted
  New-ImageConsoleStoryPause -Seconds 1.5
  Select-ImageConsoleStoryTab -Id PowerShell
  New-ImageConsoleStoryCommand -Text 'Get-ChildItem .\artifacts'
}
$story | Export-ImageConsoleStory -Path '.\navigation.gif'

Background prepares an inactive tab. Each Select step deliberately switches to a retained buffer; a pause can show that session ready and a later command continues it.

Render output captured from an actual script run

$output = & .\Invoke-EnvironmentAudit.ps1 2>&1 | Out-String -Stream -Width 110
$story = $output | New-ImageConsoleStory -CommandText '.\Invoke-EnvironmentAudit.ps1' -Dialect PowerShell
$story | Export-ImageConsoleStory -Path '.\audit-demo.svg'

The caller controls execution; the cmdlet only turns the captured lines into a deterministic presentation.

Export a portable animated GIF for chat or documentation

$story = New-ImageConsoleStory -Dialect CSharp -Title 'dotnet run - ChartForgeX' -Content {
  New-ImageConsoleStoryCommand -Text 'var chart = Chart.Create().WithTitle("Weekly builds");'
  New-ImageConsoleStoryCommand -Text 'chart.SavePng("weekly-builds.png");'
  New-ImageConsoleStoryOutput -Text 'Saved weekly-builds.png' -Style Success
}
$story | Export-ImageConsoleStory -Path '.\chart-demo.gif' -FramesPerSecond 10 -EndHoldSeconds 1.5

GIF and APNG export sample the same deterministic terminal timeline used by SVG and HTML.

Tune typing and tab reading time independently

$story = New-ImageConsoleStory -Speed Normal -TypingSpeed 36 -TabHoldSeconds 2.5 -Content {
  New-ImageConsoleStoryCommand -Text 'Invoke-ProjectBuild'
  New-ImageConsoleStoryOutput -Text 'Build completed.' -Style Success
}

TypingSpeed is measured in visible characters per second. A command-level DurationSeconds value remains the most specific override.

Parameters

-AnimationScale Int32 optional: Raster density multiplier used for animated GIF and APNG output.
-EndHoldSeconds Double optional: Completed-state hold time used for animated GIF and APNG output.
-FilePath String optional: Output file path. Supported extensions are SVG, HTML, HTM, PNG, GIF, and APNG.
-FramesPerSecond Int32 optional: Frame rate used for animated GIF and APNG output.
-MaximumFrames Int32 optional: Maximum frame budget used for animated GIF and APNG output.
-NoLoop SwitchParameter optional: Produce a single-play animated GIF or APNG instead of a repeating animation.
-PassThru SwitchParameter optional: Write the configured ChartForgeX TerminalStory to the pipeline.
-Show SwitchParameter optional: Open the generated presentation after creation.
-StoryScript ScriptBlock requiredposition: 0sets: StoryScript: Script block that receives and configures a new ChartForgeX TerminalStory.
-Content ScriptBlock requiredsets: Content: PowerShell-native authoring block that emits command, output, table, pause, tab declaration, and tab-selection steps.
-CustomPrompt String optionalsets: Content, Step, Transcript: Prompt text used when Dialect is Custom.
-Dialect TerminalDialect optionalsets: Content, Step, Transcript: Prompt dialect used for captured transcript presentations.; Possible values: PowerShell, Bash, CommandPrompt, Python, CSharp, Custom
-FontSize Double optionalsets: Content, Step, Transcript: Terminal font size used by composed and captured stories.
-InitialDelaySeconds Double optionalsets: Content, Step, Transcript: Delay before the first animated step.
-LineDelaySeconds Double optionalsets: Content, Step, Transcript: Delay between output lines.
-LineHeight Double optionalsets: Content, Step, Transcript: Terminal line height used by composed and captured stories.
-NoFinalPrompt SwitchParameter optionalsets: Content, Step, Transcript: Hide the final prompt and cursor in the completed story.
-Palette TerminalTheme optionalsets: Content, Step, Transcript: Optional custom palette, normally created by New-ImageConsoleStoryPalette.
-PngOutputScale Int32 optionalsets: Content, Step, Transcript: PNG output density multiplier used by composed and captured stories.
-Speed TerminalStoryPlaybackSpeed optionalsets: Content, Step, Transcript: Reusable playback pace. Slow leaves the most reading time, Normal is balanced, and Fast is intended for short demos.; Possible values: Slow, Normal, Fast
-TabHoldSeconds Double optionalsets: Content, Step, Transcript: Optional minimum reading time after content appears and before the active tab changes. When omitted, Speed selects the hold: Slow 2 seconds, Normal 0.9 seconds, or Fast 0.35 seconds.
-Theme String optionalsets: Content, Step, Transcript: Built-in terminal color palette used by composed and captured stories.; Possible values: Dark, PowerShell, WindowsPowerShell, Ubuntu, Campbell, Classic, Light
-Title String optionalsets: Content, Step, Transcript: Terminal title shown for captured transcript presentations.
-TypingSpeed Double optionalaliases: CharactersPerSecondsets: Content, Step, Transcript: Optional simulated command typing speed in visible characters per second. When omitted, Speed selects the rate: Slow 28, Normal 42, or Fast 72 characters per second.
-Width Int32 optionalsets: Content, Step, Transcript: Logical terminal width used by composed and captured stories.
-WindowStyle TerminalWindowStyle optionalsets: Content, Step, Transcript: Visible terminal window chrome, independent of the color palette and prompt dialect.; Possible values: MacOS, WindowsTerminal, Minimal
-WorkingDirectory String optionalsets: Content, Step, Transcript: Working directory shown in shell prompts for captured transcript presentations.
-Step ImageConsoleStoryStep[] requiredpipeline: True (ByValue)sets: Step: Typed console story steps. Accepts pipeline input and arrays created by the console story step cmdlets.
-Story TerminalStory requiredpipeline: True (ByValue)sets: Story: Native ChartForgeX terminal story to render.
-CommandText String requiredsets: Transcript: Command text shown before captured transcript lines.
-InputObject String requiredpipeline: True (ByValue)sets: Transcript: One captured output line. Accepts pipeline input and never executes the displayed command.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.