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|Linux>] [-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|Linux>] [-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|Linux>] [-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

Authored help example

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. Light and Dark use canonical ChartForgeX tokens; named shell palettes retain their own appearance.; 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, Linux
-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.