Improve HLS API with structured HlsVariant and refactor sample test

Author: bramp

.agents/skills/gh-cli/SKILL.md

@@ -0,0 +1,3 @@
+{
+    "java.compile.nullAnalysis.mode": "automatic"
+}

.vscode/settings.json

@@ -0,0 +1,10 @@
+# AI Agent Disclosure
+
+Some issue triage, responses, and maintenance tasks on this repository may be
+performed by an AI agent (GitHub Copilot) acting on behalf of @bramp.
+
+When this happens, the response will clearly state that it was written by an AI
+agent. All AI-generated responses are reviewed or approved by @bramp before or
+shortly after posting.
+
+If you have concerns about an AI-generated response, please tag @bramp directly.

AGENTS.md

@@ -0,0 +1,24 @@
+# PR Review TODO List
+
+This list tracks the next steps for the 6 open pull requests in `bramp/ffmpeg-cli-wrapper`.
+
+## 🟢 Completed
+- [x] **PR #366**: Add color_space related options to FFProbeStream
+- [x] **PR #362**: Add -map option
+
+## 🟡 Rebase Required (CI Failures)
+- [x] **PR #361**: fix/passlog-files-not-deleted
+- [ ] **PR #377**: Bump org.apache.maven.plugins:maven-gpg-plugin from 3.2.0 to 3.2.8
+  - **Action:** Rebase via Dependabot.
+  - **Details:** Standard dependency update. Current failure is due to the same transient CI issue as #361.
+
+## 🔴 Needs Update or Redesign
+- [x] **PR #294**: Add Sample Test to convert media file in hls format
+- [ ] **PR #178**: Added support for input devices/streams and tests
+  - **Action:** Architectural redesign.
+  - **Files:** `FFmpegInputBuilder.java` (new), `FFmpegBuilder.java`.
+  - **Issue:** 7 years old. Duplicates `build()` logic from output builders and hardcodes specific flags like `-video_device_number`.
+  - **Redesign Goal:** Create a shared base or interface for "Builders that can generate `-i` options" to support devices (v4l2, dshow, x11grab) without duplicating the entire option-building logic.
+
+---
+*Generated by Gemini CLI on 2026-04-03*

ISSUE_RESPONSES.md

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "gh-cli": {
+      "source": "github/awesome-copilot",
+      "sourceType": "github",
+      "computedHash": "cbe644b0c6760ae2a1eaafa39133920d889331327065d92a131675a665273e56"
+    }
+  }
+}

TODO.md

@@ -6,6 +6,8 @@
 
 import com.google.common.base.Strings;
 import com.google.common.collect.ImmutableList;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.concurrent.TimeUnit;
 import javax.annotation.CheckReturnValue;
 
@@ -16,6 +18,11 @@ public class FFmpegHlsOutputBuilder extends AbstractFFmpegOutputBuilder<FFmpegHl
   public Long hls_init_time;
   public Integer hls_list_size;
   public String hls_base_url;
+  public String hls_playlist_type;
+  public String master_pl_name;
+  public String var_stream_map;
+
+  private final List<HlsVariant> variants = new ArrayList<>();
 
   protected FFmpegHlsOutputBuilder(FFmpegBuilder parent, String filename) {
     super(parent, filename);
@@ -107,6 +114,52 @@ public FFmpegHlsOutputBuilder setHlsBaseUrl(String baseurl) {
     return this;
   }
 
+  /**
+   * Set the playlist type.
+   *
+   * @param type The playlist type (e.g. "event", "vod")
+   * @return {@link FFmpegHlsOutputBuilder}
+   */
+  public FFmpegHlsOutputBuilder setHlsPlaylistType(String type) {
+    this.hls_playlist_type = checkNotEmpty(type, "type must not be empty");
+    return this;
+  }
+
+  /**
+   * Set the master playlist name.
+   *
+   * @param name The master playlist name
+   * @return {@link FFmpegHlsOutputBuilder}
+   */
+  public FFmpegHlsOutputBuilder setMasterPlName(String name) {
+    this.master_pl_name = checkNotEmpty(name, "name must not be empty");
+    return this;
+  }
+
+  /**
+   * Set the variant stream map string manually.
+   *
+   * <p>Prefer using {@link #addVariant(HlsVariant)} for a cleaner API.
+   *
+   * @param map The variant stream map (e.g. "v:0,a:0 v:1,a:1")
+   * @return {@link FFmpegHlsOutputBuilder}
+   */
+  public FFmpegHlsOutputBuilder setVarStreamMap(String map) {
+    this.var_stream_map = checkNotEmpty(map, "map must not be empty");
+    return this;
+  }
+
+  /**
+   * Adds an HLS variant to this output.
+   *
+   * @param variant The variant configuration.
+   * @return {@link FFmpegHlsOutputBuilder}
+   */
+  public FFmpegHlsOutputBuilder addVariant(HlsVariant variant) {
+    this.variants.add(checkNotNull(variant));
+    return this;
+  }
+
   @Override
   protected void addFormatArgs(ImmutableList.Builder<String> args) {
     super.addFormatArgs(args);
@@ -129,6 +182,27 @@ protected void addFormatArgs(ImmutableList.Builder<String> args) {
     if (!Strings.isNullOrEmpty(hls_base_url)) {
       args.add("-hls_base_url", hls_base_url);
     }
+
+    if (!Strings.isNullOrEmpty(hls_playlist_type)) {
+      args.add("-hls_playlist_type", hls_playlist_type);
+    }
+
+    if (!Strings.isNullOrEmpty(master_pl_name)) {
+      args.add("-master_pl_name", master_pl_name);
+    }
+
+    if (!Strings.isNullOrEmpty(var_stream_map)) {
+      args.add("-var_stream_map", var_stream_map);
+    } else if (!variants.isEmpty()) {
+      StringBuilder sb = new StringBuilder();
+      for (int i = 0; i < variants.size(); i++) {
+        if (i > 0) {
+          sb.append(" ");
+        }
+        sb.append(variants.get(i).toString());
+      }
+      args.add("-var_stream_map", sb.toString());
+    }
   }
 
   @CheckReturnValue

skills-lock.json

@@ -0,0 +1,85 @@
+package net.bramp.ffmpeg.builder;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Represents an HLS variant stream mapping.
+ *
+ * <p>Used with {@code -var_stream_map} to group audio, video, and subtitle streams.
+ */
+public class HlsVariant {
+
+  private final List<String> streams = new ArrayList<>();
+  private String name;
+
+  public HlsVariant() {}
+
+  /**
+   * Adds a video stream to this variant.
+   *
+   * @param index The zero-based index of the video stream in the output.
+   * @return this
+   */
+  public HlsVariant addVideo(int index) {
+    checkArgument(index >= 0, "index must be >= 0");
+    streams.add("v:" + index);
+    return this;
+  }
+
+  /**
+   * Adds an audio stream to this variant.
+   *
+   * @param index The zero-based index of the audio stream in the output.
+   * @return this
+   */
+  public HlsVariant addAudio(int index) {
+    checkArgument(index >= 0, "index must be >= 0");
+    streams.add("a:" + index);
+    return this;
+  }
+
+  /**
+   * Adds a subtitle stream to this variant.
+   *
+   * @param index The zero-based index of the subtitle stream in the output.
+   * @return this
+   */
+  public HlsVariant addSubtitle(int index) {
+    checkArgument(index >= 0, "index must be >= 0");
+    streams.add("s:" + index);
+    return this;
+  }
+
+  /**
+   * Sets the name for this variant.
+   *
+   * @param name The variant name (e.g., "1080p").
+   * @return this
+   */
+  public HlsVariant setName(String name) {
+    this.name = checkNotNull(name);
+    return this;
+  }
+
+  @Override
+  public String toString() {
+    if (streams.isEmpty()) {
+      return "";
+    }
+    StringBuilder sb = new StringBuilder();
+    for (int i = 0; i < streams.size(); i++) {
+      if (i > 0) {
+        sb.append(",");
+      }
+      sb.append(streams.get(i));
+    }
+    if (name != null && !name.isEmpty()) {
+      sb.append(",name:").append(name);
+    }
+    return sb.toString();
+  }
+}