# New-ImageConsoleStory

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

Project

ImagePlayground

Automate image processing, codes, metadata, charts, topology, and visual stories from PowerShell.

[View on GitHub](https://github.com/EvotecIT/ImagePlayground) [Visit Website](#) [Releases](https://github.com/EvotecIT/ImagePlayground/releases) [Changelog](#) [Get package](https://www.powershellgallery.com/packages/ImagePlayground)

Stars **102**

Forks **7**

Open issues 

Total downloads **708,853**

Release **ImagePlayground-PowerShellModule.v3.2.7**

Language: C# Updated: 2026-11-18

Command 

**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>]
```

[#](#method-new-imageconsolestory-int32-double-string-int32-int32-switchparameter-switchparameter-switchparameter-scriptblock)

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>]
```

[#](#member-a85fd14297affa11b94433e0)

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>]
```

[#](#member-0abc4ac1671d8c2fdc27b86b)

Parameter set: `Step`

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

[#](#method-new-imageconsolestory-int32-double-string-int32-int32-switchparameter-switchparameter-switchparameter-terminalstory)

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>]
```

[#](#member-5448f77fc775ad14740eacf6)

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

```powershell
$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

```powershell
$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

```powershell
$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

```powershell
$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

```powershell
$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](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters).

Evotec API Reference Copyright 2026 Evotec Services

<!-- PowerForge markdown artifact sha256:5879906E85C56889AD8323AAAFF69CCC360D9487DA2B1CBE92E1DEFD160F1644 -->
