screenkit 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97a973d1c6ae7d7c373be709a2233a0b935fae81c706f312c03664e730088780
-  data.tar.gz: 2bf3c1093ee252e020635ef4f98632975eab1c77436e0769d9b2a3c107cd228c
+  metadata.gz: 9432b0beeacae6f145c48e9935c18d92c62c08c69ea7177a3d282db689b0d9d5
+  data.tar.gz: 9cbf970a8998f0cb3bd5778489faa0ecc521b800862c1d8c8112cb11e0232bcd
 SHA512:
-  metadata.gz: 78c95717248ebfa4fab374c612656813bdf6cd0add77dd1c4dfdc65505033c793b73c1645daeb5742670dfc0e6e5aef84100fabd5ec8cc15a011e95d88fa62e0
-  data.tar.gz: 1cca22fd0d8f922fc245be632fcbf587968dc99c402615fe8691eb1e1c45415583f8c1fd2f00c9898c3855a14fd6efe3803c3601102fe8965d563288b5acb4c8
+  metadata.gz: 4b952dc0d719ccdf1496b2ee0cb430e9ba8271e5e9373f1859d8132ed68febf86daa9ff063cbc05a75a314de32d8a279eb4336021344caf70e9cc297e8eaac37
+  data.tar.gz: 4660532603407564ab3315a0d21d6af592d5fad3179cbd7bafade4438e97708a95ba2d9eab34fd61507aee02b58c90bed5d487f7affa4951351a1d3442c37d46

data/.github/workflows/docker.yml

@@ -7,7 +7,7 @@ on:
     paths:
       - Dockerfile
     tags:
-      - v*
+      - v[0-9]+.[0-9]+.[0-9]+
   workflow_dispatch:
     inputs:
       ref:
@@ -23,7 +23,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.inputs.ref }}
 

data/CHANGELOG.md

@@ -11,6 +11,14 @@ Prefix your message with one of the following:
 - [Security] in case of vulnerabilities.
 -->
 
+# v0.0.8
+
+- [Fixed] Further improvements to support extensions.
+
+## v0.0.7
+
+- [Fixed] Improve support for extensions.
+
 ## v0.0.6
 
 - [Added] Add `--tts-preset` option to select TTS preset when exporting

data/DOCUMENTATION.md

@@ -719,7 +719,9 @@ tts:
 
 ### ElevenLabs Engine
 
-Professional AI voice synthesis.
+The ElevenLabs TTS engine requires an API key. Set it via the `--tts-api-key`
+option when exporting an episode. The API key must be prefixed with
+`eleven_labs:`, e.g. `eleven_labs:sk_c195c0131de...`.
 
 ```yaml
 tts:
@@ -764,32 +766,50 @@ module. Custom engines must implement the `generate` method:
 module ScreenKit
   module TTS
     class CustomEngine < Base
-      include Shell
-
       # Optional: Define schema path for validation
       def self.schema_path
-        ScreenKit.root_dir.join("screenkit/schemas/tts/custom_engine.json")
+        File.join(__dir__, "yourschema.json")
       end
 
       # This method is required.
-      def available?
-        enabled? && command_exist?("some-command")
+      # The keyword arguments will be all the configuration options, plus
+      # api_key and segments. If you don't care about those, remember to use
+      # the `**` operator to ignore them.
+      def self.available?(**)
+        # If you're running a local command:
+        # command_exist?("some-command")
+
+        # If you're using an API key:
+        # api_key.to_s.start_with?("#{engine_name}:")
       end
 
       # This method is required.
       def generate(text:, output_path:, log_path: nil)
-        # Optional: validate options against JSON schema.
+        # Optional, but recommended: validate options against JSON schema.
         self.class.validate!(options)
 
+        # If you need access to previous/next text, you can access the method
+        # `segments`.
+        # current_index = segments.index { it.script_content == text }
+        # next_text = segments[current_index + 1]&.script_content
+
         # Generate audio file from text
         # Write output to output_path
         # Optionally log to log_path
 
-        # Example implementation:
-        # run_command "some-command",
-        #             "-o", output_path.sub_ext(".wav"),
-        #             text,
-        #             log_path:
+        # Example calling a command (provided by ScreenKit::Shell)
+        # self.class.run_command "some-command",
+        #                        "-o", output_path.sub_ext(".wav"),
+        #                        text,
+        #                        log_path:
+
+        # Example using an API (provided by ScreenKit::HTTP)
+        # response = json_post(
+        #   url: "https://api.example.com/tts",
+        #   headers: {authorization: "Bearer #{api_key}"},
+        #   api_key:,
+        #   log_path:
+        # )
       end
     end
   end
@@ -802,6 +822,7 @@ end
 tts:
   - id: custom_engine
     engine: custom_engine # Camelized to CustomEngine
+    enabled: true
     # Add your custom options here
     api_key: your_api_key
     custom_option: value
@@ -811,6 +832,17 @@ The engine name is camelized (e.g., `custom_engine` → `CustomEngine`,
 `google_cloud` → `GoogleCloud`) and loaded as
 `ScreenKit::TTS::#{CamelizedName}`.
 
+### 3rd-party TTS Engines
+
+- [Search Github](https://github.com/topics/screenkit-tts)
+- [Google Text to Speech](https://github.com/fnando/screenkit-tts-google)
+- [Minimax Text to Speech](https://github.com/fnando/screenkit-tts-minimax)
+
+> [!TIP]
+>
+> If you host your TTS engine on Github, use the topic `screekit-tts`, so other
+> people can find it.
+
 ---
 
 ## Animations
@@ -897,6 +929,12 @@ Enter
 Sleep 2s
 ```
 
+When running tape files, the working directory will be the episode directory. If
+you're importing anything from the parent directory, you must specify relative
+paths accordingly. For instance, `episodes/001-episode-name/content/001.tape`
+would need to reference `../../resources/some-file` to access
+`resources/some-file` in the project's directory.
+
 ### Script Files
 
 Plain text files for voiceover generation:
@@ -1099,26 +1137,26 @@ be processed).
 
 ### Common Issues
 
-**"Gem not found" error:**
+#### "Gem not found" error
 
 ```bash
 bundle install
 bundle exec screenkit ...
 ```
 
-**"Schema validation failed":**
+#### Schema validation failed
 
 - Check YAML syntax
 - Verify required fields are present
 - Use schema hints with `yaml-language-server`
 
-**Missing resources:**
+#### Missing resources
 
 - Check `resources_dir` configuration
 - Verify file paths are relative to resource directories
 - Use absolute paths for system resources
 
-**TTS not working:**
+#### TTS not working
 
 - For ElevenLabs: Set `--tts-api-key`
 - For macOS `say`: Verify voice name with `say -v ?`

data/action.yml

@@ -0,0 +1,140 @@
+---
+name: ScreenKit Episode
+description: Export a screencast episode using Docker
+inputs:
+  episode:
+    description: "Episode number (e.g. 001)"
+    required: true
+  tts_preset:
+    description: "TTS preset name"
+    default: ""
+    required: false
+  tts_api_key:
+    description: "TTS API key"
+    required: false
+  overwrite:
+    description: "Regenerate files"
+    default: "false"
+    required: false
+  match:
+    description: "Match pattern for segments (e.g. 001)"
+    default: ""
+    required: false
+  github_token:
+    description: "GitHub token for cache operations"
+    required: true
+  retention:
+    description: "Retention days for artifacts"
+    default: "2"
+
+runs:
+  using: composite
+  steps:
+    - name: Generate cache keys
+      shell: bash
+      run: |
+        VOICEOVER_HASH=$(find episodes/${{ inputs.episode }}-*/scripts/*.txt -type f 2>/dev/null | sort | xargs sha256sum 2>/dev/null | sha256sum | cut -d' ' -f1 || echo "none")
+        CONTENT_HASH=$(find episodes/${{ inputs.episode }}-*/*/*.* -type f 2>/dev/null | sort | xargs sha256sum 2>/dev/null | sha256sum | cut -d' ' -f1 || echo "none")
+
+        echo "VOICEOVER_CACHE_KEY=episode-voiceover-${{ inputs.episode }}-${VOICEOVER_HASH}" >> $GITHUB_ENV
+        echo "VOICEOVER_RESTORE_KEY=episode-voiceover-${{ inputs.episode }}-" >> $GITHUB_ENV
+        echo "VIDEO_CACHE_KEY=episode-${{ inputs.episode }}-${CONTENT_HASH}" >> $GITHUB_ENV
+        echo "VIDEO_RESTORE_KEY=episode-${{ inputs.episode }}-" >> $GITHUB_ENV
+
+    - name: Find episode dir
+      shell: bash
+      run: |
+        EPISODE_DIR=$(ls -1d episodes/${{ inputs.episode }}-* | head -n 1)
+        echo "EPISODE_DIR=$EPISODE_DIR" >> $GITHUB_ENV
+
+        if [[ ! -d "$EPISODE_DIR" ]]; then
+          echo "Episode directory not found!"
+          echo "Available episodes:"
+          ls -1 episodes
+          exit 1
+        fi
+
+    - name: Restore episode voice cache
+      id: cache-voice
+      uses: actions/cache/restore@v4
+      with:
+        path: episodes/${{ inputs.episode }}-*/voiceovers
+        key: ${{ env.VOICEOVER_CACHE_KEY }}
+        restore-keys: ${{ env.VOICEOVER_RESTORE_KEY }}
+        enableCrossOsArchive: true
+
+    - name: Restore videos cache
+      id: cache-videos
+      uses: actions/cache/restore@v4
+      with:
+        path: output/${{ inputs.episode }}-*/videos/*.mp4
+        key: ${{ env.VIDEO_CACHE_KEY }}
+        restore-keys: ${{ env.VIDEO_RESTORE_KEY }}
+        enableCrossOsArchive: true
+
+    - name: Export Episode
+      shell: bash
+      id: screenkit
+      run: |
+        set -e
+        docker run \
+          --rm \
+          --cap-add=SYS_ADMIN \
+          --shm-size=2g \
+          --security-opt seccomp=unconfined \
+          -v ${{ github.workspace }}:/source \
+          fnando/screenkit:latest \
+          episode export \
+          --dir="${{ env.EPISODE_DIR }}" \
+          ${{ inputs.match != '' && format('--match {0}', inputs.match) || '' }} \
+          ${{ inputs.overwrite == 'true' && '--overwrite' || '--no-overwrite' }} \
+          ${{ inputs.tts_preset != '' && format('--tts-preset {0}', inputs.tts_preset) || '' }} \
+          ${{ inputs.tts_api_key != '' && format('--tts-api-key {0}', inputs.tts_api_key) || '' }}
+        echo "result=true" >> $GITHUB_OUTPUT
+
+    - name: Delete voice cache
+      if: steps.screenkit.outputs.result == 'true'
+      shell: bash
+      run: gh cache delete "${{ env.VOICEOVER_CACHE_KEY }}" || true
+      env:
+        GH_TOKEN: ${{ inputs.github_token }}
+
+    - name: Delete videos cache
+      if: steps.screenkit.outputs.result == 'true'
+      shell: bash
+      run: gh cache delete "${{ env.VIDEO_CACHE_KEY }}" || true
+      env:
+        GH_TOKEN: ${{ inputs.github_token }}
+
+    - name: List cache entries
+      shell: bash
+      run: |
+        echo "= Voiceover Cache ="
+        ls -la episodes/${{ inputs.episode }}-*/voiceovers || true
+        echo
+        echo "= Videos Cache ="
+        ls -la output/${{ inputs.episode }}-*/videos || true
+
+    - name: Save episode voiceover cache
+      if: steps.screenkit.outputs.result == 'true'
+      uses: actions/cache/save@v4
+      with:
+        path: episodes/${{ inputs.episode }}-*/voiceovers
+        key: ${{ env.VOICEOVER_CACHE_KEY }}
+        enableCrossOsArchive: true
+
+    - name: Save video recordings cache
+      if: steps.screenkit.outputs.result == 'true'
+      uses: actions/cache/save@v4
+      with:
+        path: output/${{ inputs.episode }}-*/videos/*.mp4
+        key: ${{ env.VIDEO_CACHE_KEY }}
+        enableCrossOsArchive: true
+
+    - name: Upload output artifacts
+      uses: actions/upload-artifact@v5
+      if: always()
+      with:
+        name: output
+        path: output
+        retention-days: ${{ inputs.retention }}

data/lib/screenkit/callout/styles/base.rb

@@ -4,6 +4,8 @@ module ScreenKit
   class Callout
     module Styles
       class Base
+        require_relative "../../schema_validator"
+
         attr_reader :source, :output_path, :log_path
         attr_accessor :options
 
@@ -16,6 +18,11 @@ module ScreenKit
           @options = options
         end
 
+        # Wrap text to fit within the specified maximum width.
+        # @param text [String] The text to wrap.
+        # @param max_width [Integer] The maximum width in pixels.
+        # @param font_size [Integer] The font size in points.
+        # @return [Array<String>] The wrapped lines of text.
         def text_wrap(text, max_width:, font_size:)
           words = text.to_s.split(/\s+/)
           width_factor = 0.6
@@ -42,10 +49,19 @@ module ScreenKit
           text.gsub("'", "\\\\'")
         end
 
+        # Remove a file if it exists.
+        # @param path [String] The file path to remove.
         def remove_file(path)
           File.unlink(path) if path && File.exist?(path)
         end
 
+        # Render text into an image using MiniMagick.
+        # @param text [String] The text to render.
+        # @param style [TextStyle] The text style to apply.
+        # @param width [Integer] The width of the text image.
+        # @param type [String] The ImageMagick text type (e.g., "caption").
+        # @return [Array] The path to the generated text image, width, and
+        # height.
         def render_text_image(text:, style:, width:, type:)
           return [nil, 0, 0] if text.to_s.empty?
 

data/lib/screenkit/cli/episode.rb

@@ -61,9 +61,13 @@ module ScreenKit
       def export
         puts Banner.banner if options.banner
 
-        episode_config = Config::Episode.load_file(
-          File.join(options.dir, "config.yml")
-        )
+        episode_config = File.join(options.dir, "config.yml")
+
+        episode_config = if File.file?(episode_config)
+                           Config::Episode.load_file(episode_config)
+                         else
+                           {}
+                         end
 
         options.require.each { require(it) }
 

data/lib/screenkit/content_type.rb

@@ -4,7 +4,7 @@ module ScreenKit
   module ContentType
     def self.video = %w[mp4 webm mov]
     def self.audio = %w[mp3 wav m4a aac aiff]
-    def self.image = %w[gif jpg jpeg png]
+    def self.image = %w[gif jpg jpeg png tiff]
     def self.demotape = %w[tape]
 
     def self.all = video + image + demotape

data/lib/screenkit/core_ext/json.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module ScreenKit
   module CoreExt
     refine JSON.singleton_class do

data/lib/screenkit/core_ext/string.rb

@@ -7,6 +7,8 @@ module ScreenKit
         unicode_normalize(:nfkd)
           .delete("'")
           .gsub(/[^\x00-\x7F]/, "")
+          .gsub(/([a-z\d])([A-Z])/, '\1-\2')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2')
           .gsub(/[^-\w]+/xim, "-")
           .tr("_", "-")
           .gsub(/-+/xm, "-")
@@ -14,6 +16,10 @@ module ScreenKit
           .downcase
       end
 
+      def underscore
+        dasherize.tr("-", "_")
+      end
+
       def camelize(first_letter = :upper)
         split(/_|-/).map.with_index do |part, index|
           if index.zero? && first_letter == :lower

data/lib/screenkit/core_ext.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "core_ext/string"
+require_relative "core_ext/json"

data/lib/screenkit/exporter/demotape.rb

@@ -27,7 +27,8 @@ module ScreenKit
                     "--fps", 24,
                     "--overwrite",
                     "--output-path", output_path,
-                    log_path:
+                    log_path:,
+                    chdir: demotape_path.parent.parent
       end
 
       def options_to_args(options)

data/lib/screenkit/exporter/episode.rb

@@ -46,18 +46,11 @@ module ScreenKit
       end
 
       def tts_engine
-        @tts_engine ||=
-          if options.tts_preset
-            tts_engines.find do |engine|
-              engine.id == options.tts_preset && engine.available?
-            end
-          else
-            tts_engines.find(&:available?)
-          end
+        tts_engines.first
       end
 
-      def tts_engines
-        @tts_engines ||= begin
+      def tts_config
+        @tts_config ||= begin
           project_tts = if project_config.tts.is_a?(Hash)
                           [project_config.tts]
                         else
@@ -70,10 +63,23 @@ module ScreenKit
                           Array(config.tts)
                         end
 
-          (episode_tts + project_tts).map do |opts|
-            TTS.const_get(opts[:engine].camelize)
-               .new(**opts.except(:engine), api_key: options.tts_api_key)
-          end
+          episode_tts + project_tts
+        end
+      end
+
+      def tts_engines
+        @tts_engines ||= tts_config.filter_map do |opts|
+          next unless opts[:enabled]
+
+          api_key = options.tts_api_key
+          tts_class = TTS.const_get(opts[:engine].camelize)
+          tts_preset = options.tts_preset.to_s
+
+          next if !tts_preset.empty? && tts_preset != opts[:id]
+          next unless tts_class.available?(api_key:, **opts)
+
+          opts = opts.except(:engine, :enabled)
+          tts_class.new(**opts, api_key:, segments:)
         end
       end
 

data/lib/screenkit/exporter/segment.rb

@@ -177,6 +177,10 @@ module ScreenKit
                     log_path:
       end
 
+      def script_content
+        @script_content ||= script_path.read if script_path.file?
+      end
+
       def create_voiceover(log_path:)
         return if voiceover_path&.file? && !episode.options.overwrite
         return unless script_path.file?
@@ -185,7 +189,7 @@ module ScreenKit
         FileUtils.mkdir_p(voiceover_path.dirname)
 
         episode.tts_engine.generate(
-          text: script_path.read,
+          text: script_content,
           output_path: voiceover_path,
           log_path:
         )

data/lib/screenkit/exporter/video.rb

@@ -9,8 +9,12 @@ module ScreenKit
       # The path to the input video file.
       attr_reader :input_path
 
-      def initialize(input_path:)
+      # The path to the log file.
+      attr_reader :log_path
+
+      def initialize(input_path:, log_path: nil)
         @input_path = input_path
+        @log_path = log_path
       end
 
       def export(output_path)
@@ -26,7 +30,8 @@ module ScreenKit
                     "-r", "24",
                     "-c:v", "libx264",
                     "-y",
-                    output_path
+                    output_path,
+                    log_path:
       end
     end
   end

data/lib/screenkit/generators/episode/config.yml.erb

@@ -1,106 +1,11 @@
 ---
 # yaml-language-server: $schema=https://screenkit.dev/schemas/episode.json
 
-# The episode title. When there are no linebreaks, they will be inferred based
-# on the approximate text width.
-title: "CREATING SCREENCASTS WITH SCREENKIT"
-
-# Callouts are informational boxes that on the screen during the
-# video (also known as lower thirds).
-#
-# The project's configuration can define the callout structure, while the
-# episode configuration can define the content and timing.
-callouts_styles:
-  - type: info
-    title: "ScreenKit"
-    body: "Visit https://github.com/fnando/screenkit to learn more."
-    starts_at: 3
-    duration: 5
-    width: 600
-
-# The background music to be played during the episode.
-# When not set, the backtrack will be defined by using the project's
-# `backtrack_dir` configuration, and a track will be randomly selected.
-# To disable the backtrack entirely, use `backtrack: false`.
-# backtrack: resources/backtrack.mp3
-
-# Define episode-specific scene configurations.
-# When present, this will have higher precedence over the project's
-# configuration, so you can have different intro/outro for each episode.
-# scenes:
-#   intro:
-#     # The duration of the intro scene in seconds.
-#     duration: 5.5
-#
-#     # The fade-in duration in seconds.
-#     fade_in: 0
-#
-#     # The fade-out duration in seconds.
-#     fade_out: 0.5
-#
-#     # The background color/image of the intro scene.
-#     background: "#100f50"
-#
-#     # The title text to be displayed in the intro scene.
-#     title:
-#       x: 100
-#       y: 300
-#       font_path: open-sans/OpenSans-ExtraBold.ttf
-#       size: 144
-#       color: "#ffffff"
-#
-#     # The logo to be displayed in the video intro.
-#     # Works best with a transparent PNG file in high resolution (at least 2x the
-#     # size it'll be displayed).
-#     logo:
-#       path: images/logo.png
-#       x: 100
-#       y: 200
-#       width: 200
-#       height: 34
-#
-#     # The sound to be played along with the logo in the intro.
-#     # This must correspond to a sound file in the sounds directory, with any
-#     # audio extension (e.g. mp3, m4a, wav).
-#     sound: sounds/chime.mp3
-#
-#   outro:
-#     # The duration of the outro scene in seconds.
-#     duration: 3.5
-#
-#     # The fade-in duration in seconds.
-#     fade_in: 0.5
-#
-#     # The fade-out duration in seconds.
-#     fade_out: 0.5
-#
-#     # The background color/image of the outro scene.
-#     background: "#100f50"
-#
-#     # The sound to be played along with the logo in the outro.
-#     sound: sounds/chime.mp3
-#
-#     # The logo to be displayed in the video outro.
-#     logo:
-#       path: images/logo.png
-#       x: center
-#       y: center
-#       width: 500
-#
-#   segment:
-#     # The duration of the crossover transition between segments in seconds.
-#     crossfade_duration: 0.5
-
-# Define episode-specific voice configuration.
-# When present, this will have higher precedence over the project's
-# configuration, so you can have different intro/outro segments for each
-# episode.
-# tts:
-#   engine: elevenlabs
-#   voice_id: 56AoDkrOh6qfVPDXZ7Pt
-#   language_code: en
-#   voice_settings:
-#     speed: 0.9
-#     stability: 0.5
-#     similarity: 0.75
-#     style: 0.0
+# The episode title (displayed in intro scene).
+# Line breaks are inferred based on approximate text width.
+title: <%= options.title.to_yaml[4..] %>
+
+# Episode-specific overrides for global configuration.
+# Use an editor with JSON Schema support to see available options and
+# autocomplete.
+# Schema: https://screenkit.dev/schemas/episode.json

data/lib/screenkit/generators/project/.github/screenkit.yml

@@ -0,0 +1,48 @@
+---
+name: Screenkit
+
+on:
+  workflow_dispatch:
+    inputs:
+      episode:
+        type: string
+        description: "Episode number (e.g. 001)"
+        required: true
+      tts_preset:
+        description: "TTS preset name"
+        default: ""
+        type: choice
+        options:
+          - ""
+          - say
+          - espeak
+          - eleven_labs
+          - eleven_labs_mp3_192k
+      match:
+        type: string
+        description: "Match pattern for segments (e.g. 001)"
+        default: ""
+      overwrite:
+        type: boolean
+        description: "Regenerate files"
+
+jobs:
+  screenkit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Run Screenkit
+        uses: fnando/screenkit@v1
+        with:
+          episode: ${{ github.event.inputs.episode }}
+          tts_preset: ${{ github.event.inputs.tts_preset }}
+          tts_api_key: ${{ secrets.TTS_API_KEY }}
+          overwrite: ${{ github.event.inputs.overwrite }}
+          match: ${{ github.event.inputs.match }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

data/lib/screenkit/generators/project.rb

@@ -22,6 +22,7 @@ module ScreenKit
       def copy_files
         copy_file "screenkit.yml"
         directory "resources", exclude_pattern: /DS_Store/
+        directory ".github", exclude_pattern: /DS_Store/
       end
 
       def bundle_install
@@ -32,6 +33,12 @@ module ScreenKit
         end
       end
 
+      def instructions
+        cmd = set_color("screenkit episode new --title TITLE", :blue)
+        path = set_color(destination_root, :blue)
+        say "\nTo create a new episode, run #{cmd} from #{path}"
+      end
+
       no_commands do
         # Add helper methods here
       end

data/lib/screenkit/http.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ScreenKit
+  module HTTP
+    # Sends a POST request.
+    # @param url [String] The request URL.
+    # @param params [Hash] The request parameters.
+    # @param headers [Hash] The request headers.
+    # @param api_key [String] The API key to redact from logs.
+    # @param log_path [String, nil] The path to log the request details.
+    # @return [Aitch::Response] The response.
+    def post(url:, params:, headers:, api_key:, log_path: nil)
+      if log_path
+        File.open(log_path, "w") do |f|
+          f << JSON.pretty_generate(url:, params:, headers:)
+        end
+      end
+
+      client = Aitch::Namespace.new
+      client.configure do |config|
+        config.logger = Logger.new(log_path) if log_path
+      end
+
+      client.post(
+        url:,
+        params:,
+        options: {expect: 200},
+        headers: headers.merge(user_agent: "ScreenKit/#{ScreenKit::VERSION}")
+      )
+    ensure
+      redact_file(log_path, api_key)
+    end
+
+    # Sends a JSON POST request.
+    # @param url [String] The request URL.
+    # @param params [Hash] The request parameters.
+    # @param headers [Hash] The request headers.
+    # @param api_key [String] The API key to redact from logs.
+    # @param log_path [String, nil] The path to log the request details.
+    # @return [Aitch::Response] The response.
+    def json_post(headers:, **)
+      headers = headers.merge(content_type: "application/json")
+      post(headers:, **)
+    end
+
+    # Redacts sensitive text from a file.
+    # @param path [String] The file path.
+    # @param text [String] The text to redact.
+    # @return [void]
+    def redact_file(path, text)
+      return unless path
+      return unless File.file?(path)
+
+      content = File.read(path).gsub(text, "[REDACTED]")
+      File.write(path, content)
+    end
+  end
+end

data/lib/screenkit/shell.rb

@@ -20,9 +20,9 @@ module ScreenKit
       !`which #{command}`.strip.empty?
     end
 
-    def run_command(command, *args, log_path: nil)
+    def run_command(command, *args, log_path: nil, **)
       args = args.flatten.compact.map(&:to_s)
-      stdout, stderr, status = Open3.capture3(command, *args)
+      stdout, stderr, status = Open3.capture3(command, *args, **)
       exit_code = status.exitstatus
 
       if exit_code&.nonzero?

data/lib/screenkit/tts/base.rb

@@ -1,9 +1,23 @@
 # frozen_string_literal: true
 
+require "json-schema"
+require "aitch"
+require "logger"
+
 module ScreenKit
   module TTS
     class Base
+      require_relative "../schema_validator"
+      require_relative "../shell"
+      require_relative "../http"
+      require_relative "../core_ext"
+      require_relative "../version"
+
       extend SchemaValidator
+      extend Shell
+      include HTTP
+
+      using CoreExt
 
       # Additional options for the tts engine.
       attr_reader :options
@@ -11,14 +25,35 @@ module ScreenKit
       # The preset name for the tts engine.
       attr_reader :id
 
-      def initialize(id: nil, enabled: true, **options)
-        @enabled = enabled
+      # The list of segments.
+      # This is available so that engines can contextually generate audio, for
+      # instance, by providing previous/next text (e.g. Eleven Labs).
+      attr_reader :segments
+
+      # The API key for the tts engine, if applicable.
+      attr_reader :api_key
+
+      # Detects if the tts engine is available.
+      def self.available?(**)
+        false
+      end
+
+      def self.engine_name
+        name.split("::").last.underscore
+      end
+
+      def self.api_key_prefix
+        "#{engine_name}:"
+      end
+
+      def initialize(id: nil, segments: nil, api_key: nil, **options)
+        @segments = Array(segments)
         @options = options
         @id = id
-      end
 
-      def enabled?
-        @enabled
+        return unless api_key
+
+        @api_key = api_key.delete_prefix("#{self.class.engine_name}:")
       end
     end
   end

data/lib/screenkit/tts/eleven_labs.rb

@@ -3,44 +3,40 @@
 module ScreenKit
   module TTS
     class ElevenLabs < Base
+      include HTTP
+
       def self.schema_path
         ScreenKit.root_dir
                  .join("screenkit/schemas/tts/elevenlabs.json")
       end
 
-      # The Eleven Labs API key.
-      attr_reader :api_key
-
-      def initialize(api_key:, **)
-        super(**)
-        @api_key = api_key
+      def self.available?(api_key: nil, **)
+        api_key.to_s.start_with?(api_key_prefix)
       end
 
-      def available?
-        enabled? && !api_key.to_s.empty?
+      def all_texts
+        @all_texts ||= segments.map(&:script_content)
       end
 
       def generate(output_path:, text:, log_path: nil)
-        self.class.validate!(options)
-        voice_id = options.delete(:voice_id)
+        voice_id = options[:voice_id]
+
+        current_index = all_texts.index { it == text }
 
-        if log_path
-          File.open(log_path, "w") do |f|
-            f << JSON.pretty_generate(options.merge(text:))
-          end
+        if current_index
+          previous_text = all_texts[current_index - 1]
+          next_text = all_texts[current_index + 1]
         end
 
-        require "aitch"
+        params = options.merge(text:, previous_text:, next_text:)
+                        .except(:voice_id)
 
-        response = Aitch.post(
+        response = json_post(
           url: "https://api.elevenlabs.io/v1/text-to-speech/#{voice_id}",
-          body: JSON.dump(options.merge(text:)),
-          options: {expect: 200},
-          headers: {
-            "content-type": "application/json",
-            "user-agent": "ScreenKit/#{ScreenKit::VERSION}",
-            "xi-api-key": api_key
-          }
+          params:,
+          headers: {"xi-api-key": api_key},
+          api_key:,
+          log_path:
         )
 
         File.binwrite(output_path, response.body)

data/lib/screenkit/tts/espeak.rb

@@ -3,14 +3,14 @@
 module ScreenKit
   module TTS
     class Espeak < Base
-      include Shell
+      extend Shell
 
-      def self.schema_path
-        ScreenKit.root_dir.join("screenkit/schemas/tts/espeak.json")
+      def self.available?(**)
+        command_exist?("espeak")
       end
 
-      def available?
-        enabled? && command_exist?("espeak")
+      def self.schema_path
+        ScreenKit.root_dir.join("screenkit/schemas/tts/espeak.json")
       end
 
       def generate(text:, output_path:, log_path: nil)
@@ -18,12 +18,12 @@ module ScreenKit
 
         {voice: nil, rate: nil}.merge(options) => {voice:, rate:}
 
-        run_command "espeak",
-                    (["-v", voice] if voice),
-                    (["-s", rate] if rate),
-                    "-w", output_path.sub_ext(".wav"),
-                    text,
-                    log_path:
+        self.class.run_command "espeak",
+                               (["-v", voice] if voice),
+                               (["-s", rate] if rate),
+                               "-w", output_path.sub_ext(".wav"),
+                               text,
+                               log_path:
       end
     end
   end

data/lib/screenkit/tts/say.rb

@@ -3,14 +3,14 @@
 module ScreenKit
   module TTS
     class Say < Base
-      include Shell
+      extend Shell
 
       def self.schema_path
         ScreenKit.root_dir.join("screenkit/schemas/tts/say.json")
       end
 
-      def available?
-        enabled? && command_exist?("say")
+      def self.available?(**)
+        command_exist?("say")
       end
 
       def generate(text:, output_path:, log_path: nil)
@@ -18,12 +18,12 @@ module ScreenKit
 
         {voice: nil, rate: nil}.merge(options) => {voice:, rate:}
 
-        run_command "say",
-                    (["-v", voice] if voice),
-                    (["-r", rate] if rate),
-                    "-o", output_path.sub_ext(".aiff"),
-                    text,
-                    log_path:
+        self.class.run_command "say",
+                               (["-v", voice] if voice),
+                               (["-r", rate] if rate),
+                               "-o", output_path.sub_ext(".aiff"),
+                               text,
+                               log_path:
       end
     end
   end

data/lib/screenkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ScreenKit
-  VERSION = "0.0.6"
+  VERSION = "0.0.8"
 end

data/lib/screenkit.rb

@@ -1,3 +1,81 @@
 # frozen_string_literal: true
 
-require_relative "screen_kit"
+require "thor"
+require "thor/completion"
+require "yaml"
+require "json-schema"
+require "mini_magick"
+require "pathname"
+require "tty-spinner"
+require "etc"
+require "securerandom"
+require "demo_tape/duration"
+require "aitch"
+
+module ScreenKit
+  require_relative "screenkit/version"
+  require_relative "screenkit/duration"
+  require_relative "screenkit/core_ext"
+  require_relative "screenkit/content_type"
+  require_relative "screenkit/anchor"
+  require_relative "screenkit/banner"
+  require_relative "screenkit/time_formatter"
+  require_relative "screenkit/spacing"
+  require_relative "screenkit/watermark"
+  require_relative "screenkit/spinner"
+  require_relative "screenkit/shell"
+  require_relative "screenkit/http"
+  require_relative "screenkit/schema_validator"
+  require_relative "screenkit/generators/project"
+  require_relative "screenkit/generators/episode"
+  require_relative "screenkit/config/base"
+  require_relative "screenkit/config/project"
+  require_relative "screenkit/config/episode"
+  require_relative "screenkit/callout"
+  require_relative "screenkit/callout/text_style"
+  require_relative "screenkit/callout/styles/base"
+  require_relative "screenkit/transition"
+  require_relative "screenkit/parallel_processor"
+  require_relative "screenkit/cli"
+  require_relative "screenkit/cli/base"
+  require_relative "screenkit/cli/episode"
+  require_relative "screenkit/cli/root"
+  require_relative "screenkit/animation_filters"
+  require_relative "screenkit/tts/base"
+  require_relative "screenkit/path_lookup"
+  require_relative "screenkit/sound"
+  require_relative "screenkit/utils"
+  require_relative "screenkit/logfile"
+  require_relative "screenkit/exporter/intro"
+  require_relative "screenkit/exporter/outro"
+  require_relative "screenkit/exporter/demotape"
+  require_relative "screenkit/exporter/episode"
+  require_relative "screenkit/exporter/segment"
+  require_relative "screenkit/exporter/image"
+  require_relative "screenkit/exporter/video"
+
+  require_files = lambda do |pattern|
+    Gem.find_files_from_load_path(pattern).each do |path|
+      next if path.include?("test")
+
+      require(path)
+    end
+  end
+
+  # Load all files that may be available as plugins.
+  require_files.call("screenkit/callout/styles/*.rb")
+  require_files.call("screenkit/tts/*.rb")
+
+  def self.root_dir
+    @root_dir ||= Pathname(__dir__)
+  end
+
+  # Raised when the configuration schema is invalid.
+  InvalidConfigSchemaError = Class.new(StandardError)
+
+  # Raised when a file is not found.
+  FileNotFoundError = Class.new(StandardError)
+
+  # Raised when a file entry is not found in the lookup.
+  FileEntryNotFoundError = Class.new(StandardError)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: screenkit
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Nando Vieira
@@ -276,10 +276,10 @@ files:
 - LICENSE.md
 - README.md
 - Rakefile
+- action.yml
 - bin/console
 - bin/setup
 - exe/screenkit
-- lib/screen_kit.rb
 - lib/screenkit.rb
 - lib/screenkit/anchor.rb
 - lib/screenkit/animation_filters.rb
@@ -298,6 +298,7 @@ files:
 - lib/screenkit/config/episode.rb
 - lib/screenkit/config/project.rb
 - lib/screenkit/content_type.rb
+- lib/screenkit/core_ext.rb
 - lib/screenkit/core_ext/json.rb
 - lib/screenkit/core_ext/string.rb
 - lib/screenkit/duration.rb
@@ -314,6 +315,7 @@ files:
 - lib/screenkit/generators/episode/content/001.tape
 - lib/screenkit/generators/episode/scripts/001.txt
 - lib/screenkit/generators/project.rb
+- lib/screenkit/generators/project/.github/screenkit.yml
 - lib/screenkit/generators/project/Gemfile.erb
 - lib/screenkit/generators/project/resources/backtracks/default.aac
 - lib/screenkit/generators/project/resources/fonts/open-sans/OFL.txt
@@ -326,6 +328,7 @@ files:
 - lib/screenkit/generators/project/resources/sounds/pop.mp3
 - lib/screenkit/generators/project/resources/sounds/whoosh.mp3
 - lib/screenkit/generators/project/screenkit.yml
+- lib/screenkit/http.rb
 - lib/screenkit/logfile.rb
 - lib/screenkit/parallel_processor.rb
 - lib/screenkit/path_lookup.rb
@@ -385,10 +388,10 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/fnando/screenkit
   bug_tracker_uri: https://github.com/fnando/screenkit/issues
-  source_code_uri: https://github.com/fnando/screenkit/tree/v0.0.6
-  changelog_uri: https://github.com/fnando/screenkit/tree/v0.0.6/CHANGELOG.md
-  documentation_uri: https://github.com/fnando/screenkit/tree/v0.0.6/README.md
-  license_uri: https://github.com/fnando/screenkit/tree/v0.0.6/LICENSE.md
+  source_code_uri: https://github.com/fnando/screenkit/tree/v0.0.8
+  changelog_uri: https://github.com/fnando/screenkit/tree/v0.0.8/CHANGELOG.md
+  documentation_uri: https://github.com/fnando/screenkit/tree/v0.0.8/README.md
+  license_uri: https://github.com/fnando/screenkit/tree/v0.0.8/LICENSE.md
 rdoc_options: []
 require_paths:
 - lib

data/lib/screen_kit.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-require "thor"
-require "thor/completion"
-require "yaml"
-require "json-schema"
-require "mini_magick"
-require "pathname"
-require "tty-spinner"
-require "etc"
-require "securerandom"
-require "demo_tape/duration"
-
-module ScreenKit
-  require_relative "screenkit/version"
-  require_relative "screenkit/duration"
-  require_relative "screenkit/core_ext/string"
-  require_relative "screenkit/core_ext/json"
-  require_relative "screenkit/content_type"
-  require_relative "screenkit/anchor"
-  require_relative "screenkit/banner"
-  require_relative "screenkit/time_formatter"
-  require_relative "screenkit/spacing"
-  require_relative "screenkit/watermark"
-  require_relative "screenkit/spinner"
-  require_relative "screenkit/shell"
-  require_relative "screenkit/schema_validator"
-  require_relative "screenkit/generators/project"
-  require_relative "screenkit/generators/episode"
-  require_relative "screenkit/config/base"
-  require_relative "screenkit/config/project"
-  require_relative "screenkit/config/episode"
-  require_relative "screenkit/callout"
-  require_relative "screenkit/callout/text_style"
-  require_relative "screenkit/callout/styles/base"
-  require_relative "screenkit/transition"
-  require_relative "screenkit/parallel_processor"
-  require_relative "screenkit/cli"
-  require_relative "screenkit/cli/base"
-  require_relative "screenkit/cli/episode"
-  require_relative "screenkit/cli/root"
-  require_relative "screenkit/animation_filters"
-  require_relative "screenkit/tts/base"
-  require_relative "screenkit/path_lookup"
-  require_relative "screenkit/sound"
-  require_relative "screenkit/utils"
-  require_relative "screenkit/logfile"
-  require_relative "screenkit/exporter/intro"
-  require_relative "screenkit/exporter/outro"
-  require_relative "screenkit/exporter/demotape"
-  require_relative "screenkit/exporter/episode"
-  require_relative "screenkit/exporter/segment"
-  require_relative "screenkit/exporter/image"
-  require_relative "screenkit/exporter/video"
-
-  require_files = lambda do |pattern|
-    Gem.find_files_from_load_path(pattern).each do |path|
-      next if path.include?("test")
-
-      require(path)
-    end
-  end
-
-  # Load all files that may be available as plugins.
-  require_files.call("screenkit/callout/styles/*.rb")
-  require_files.call("screenkit/tts/*.rb")
-
-  def self.root_dir
-    @root_dir ||= Pathname(__dir__)
-  end
-
-  # Raised when the configuration schema is invalid.
-  InvalidConfigSchemaError = Class.new(StandardError)
-
-  # Raised when a file is not found.
-  FileNotFoundError = Class.new(StandardError)
-
-  # Raised when a file entry is not found in the lookup.
-  FileEntryNotFoundError = Class.new(StandardError)
-end