Termcast app, to record/save sessions, compatible with asciinema

Author: migueldeicaza

Package.swift

@@ -12,13 +12,16 @@ let package = Package(
     ],
     products: [
         .executable(name: "SwiftTermFuzz", targets: ["SwiftTermFuzz"]),
+        .executable(name: "termcast", targets: ["Termcast"]),
         //.executable(name: "CaptureOutput", targets: ["CaptureOutput"]),
         .library(
             name: "SwiftTerm",
             targets: ["SwiftTerm"]
         ),
     ],
-    dependencies: [],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0")
+    ],
     targets: [
         .target(
             name: "SwiftTerm",
@@ -30,6 +33,14 @@ let package = Package(
             dependencies: ["SwiftTerm"],
             path: "Sources/SwiftTermFuzz"
         ),
+        .executableTarget (
+            name: "Termcast",
+            dependencies: [
+                "SwiftTerm",
+                .product(name: "ArgumentParser", package: "swift-argument-parser")
+            ],
+            path: "Sources/Termcast"
+        ),
 //        .target (
 //            name: "CaptureOutput",
 //            dependencies: ["SwiftTerm"],

README.md

@@ -54,6 +54,7 @@ Features
 * Proper CoreText rendering can munch through the hardened Unicode test suites.
 * Sixel graphics (Use img2sixel to test)
 * iTerm2-style graphic rendering (Use imgcat to test)
+* Terminal session recording and playback with termcast
 * Fuzzed and abused
 * Seems pretty fast to me
 
@@ -103,7 +104,53 @@ The core library currently does not provide a convenient way to connect to SSH,
 to avoid the additional dependency.   But this git module references a module that pulls
 a precompiled SSH client ([Frugghi's SwiftSH](https://github.com/migueldeicaza/SwiftSH)), along with 
 a [`UIKitSsshTerminalView`](https://github.com/migueldeicaza/SwiftTerm/blob/main/TerminalApp/iOSTerminal/UIKitSshTerminalView.swift)
-in the iOS sample that that connects the `TerminalView` for iOS to an SSH connection.  
+in the iOS sample that that connects the `TerminalView` for iOS to an SSH connection.
+
+## Termcast - Terminal Recording and Playback
+
+SwiftTerm includes a `termcast` command-line tool that can record and playback terminal sessions in the [asciinema](https://asciinema.org/) `.cast` format. This tool is built using SwiftTerm's `LocalProcess` functionality.
+
+### Recording Sessions
+
+To record a terminal session:
+
+```bash
+swift run termcast record output.cast
+```
+
+Options:
+- `--command` / `-c`: Specify a command to run (defaults to your shell)
+- `--timeout` / `-t`: Set an automatic timeout in seconds
+
+Examples:
+```bash
+# Record an interactive shell session
+swift run termcast record my-session.cast
+
+# Record a specific command
+swift run termcast record -c "ls -la && echo 'Done'" command-demo.cast
+
+# Record with a 30-second timeout
+swift run termcast record --timeout 30 timed-session.cast
+```
+
+### Playing Back Sessions
+
+To playback a recorded session:
+
+```bash
+swift run termcast playback my-session.cast
+```
+
+The playback will show the recorded terminal session with proper timing, including both input and output as they occurred during recording.
+
+### Features
+
+- **Full input/output capture**: Records both user input and program output with precise timing
+- **Raw terminal mode**: Properly handles terminal control sequences and special keys
+- **asciinema compatibility**: Uses the standard `.cast` format for interoperability
+- **Live display**: Shows the session live while recording
+- **Proper terminal handling**: Maintains correct line endings and terminal state  
 
 Working on SwiftTerm
 ====================

Sources/Termcast/AsciicastFormat.swift

@@ -0,0 +1,44 @@
+import Foundation
+
+struct AsciicastHeader: Codable {
+    let version: Int
+    let width: Int
+    let height: Int
+    let timestamp: TimeInterval
+    let command: String?
+    let title: String?
+    let env: [String: String]?
+}
+
+enum AsciicastEventType: String, Codable {
+    case output = "o"
+    case input = "i"
+    case resize = "r"
+    case marker = "m"
+}
+
+struct AsciicastEvent: Codable {
+    let time: TimeInterval
+    let eventType: AsciicastEventType
+    let eventData: String
+
+    init(time: TimeInterval, eventType: AsciicastEventType, eventData: String) {
+        self.time = time
+        self.eventType = eventType
+        self.eventData = eventData
+    }
+
+    init(from decoder: Decoder) throws {
+        var container = try decoder.unkeyedContainer()
+        self.time = try container.decode(TimeInterval.self)
+        self.eventType = try container.decode(AsciicastEventType.self)
+        self.eventData = try container.decode(String.self)
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.unkeyedContainer()
+        try container.encode(time)
+        try container.encode(eventType)
+        try container.encode(eventData)
+    }
+}

Sources/Termcast/TermcastPlayer.swift

@@ -0,0 +1,86 @@
+import Foundation
+
+class TermcastPlayer {
+    private let decoder = JSONDecoder()
+    
+    func playback(from filePath: String) throws {
+        let url = URL(fileURLWithPath: filePath)
+        let content = try String(contentsOf: url, encoding: .utf8)
+        let lines = content.components(separatedBy: .newlines).filter { !$0.isEmpty }
+        
+        guard !lines.isEmpty else {
+            throw TermcastError.invalidFile("Empty cast file")
+        }
+        
+        // Parse header
+        let headerData = lines[0].data(using: .utf8)!
+        let header = try decoder.decode(AsciicastHeader.self, from: headerData)
+        
+        // Set terminal size if possible
+        setTerminalSize(width: header.width, height: header.height)
+        
+        // Parse and replay events
+        var lastTime: TimeInterval = 0
+        
+        for line in lines.dropFirst() {
+            let eventData = line.data(using: .utf8)!
+            let event = try decoder.decode(AsciicastEvent.self, from: eventData)
+            
+            // Calculate delay since last event
+            let delay = event.time - lastTime
+            if delay > 0 {
+                usleep(UInt32(delay * 1_000_000)) // Convert to microseconds
+            }
+            
+            // Handle different event types
+            switch event.eventType {
+            case .output:
+                print(event.eventData, terminator: "")
+                fflush(stdout)
+            case .resize:
+                handleResize(event.eventData)
+            case .input, .marker:
+                // For playback, we typically don't replay input or markers
+                // But we could add options to show them if needed
+                break
+            }
+            
+            lastTime = event.time
+        }
+        
+        print() // Final newline
+    }
+    
+    private func setTerminalSize(width: Int, height: Int) {
+        // Try to set the terminal size using ANSI escape codes
+        // This may not work in all terminals, but it's worth trying
+        print("\u{001B}[8;\(height);\(width)t", terminator: "")
+        fflush(stdout)
+    }
+    
+    private func handleResize(_ data: String) {
+        // Parse resize data in format "WIDTHxHEIGHT"
+        let components = data.components(separatedBy: "x")
+        guard components.count == 2,
+              let width = Int(components[0]),
+              let height = Int(components[1]) else {
+            return
+        }
+        
+        setTerminalSize(width: width, height: height)
+    }
+}
+
+enum TermcastError: Error, LocalizedError {
+    case invalidFile(String)
+    case fileNotFound(String)
+    
+    var errorDescription: String? {
+        switch self {
+        case .invalidFile(let message):
+            return "Invalid cast file: \(message)"
+        case .fileNotFound(let path):
+            return "File not found: \(path)"
+        }
+    }
+}