Create compilable, tested EXAMPLES.md to replace wiki

[bramp]

Create compilable, tested EXAMPLES.md to replace wiki

Problem

The wiki has 12 community-contributed examples, but they have three problems:

1. Hard to discover — most users never find the wiki
2. Stale — examples use deprecated APIs (e.g., FFmpegBuilder.Strict.EXPERIMENTAL instead of Strict.EXPERIMENTAL, constructor-based paths instead of no-arg constructors)
3. Never tested — code may not compile or run with the current version

Meanwhile, the same 10-15 questions recur in issues repeatedly (#49, #69, #71, #81, #96, #107, #112, #125, #128, #146, #161, #169, #174, #185, #215, #248, #275, #282, #286, #288, #301). A well-maintained examples document would reduce these significantly.

Solution

Create a compilable Java test file containing all examples, and a Python script that extracts them into a generated EXAMPLES.md. This gives us:

• Tested — examples are compiled and run by CI on every commit
• Discoverable — EXAMPLES.md lives in the repo root, linked from README
• Current — if an API changes, the test breaks, so examples stay up to date

Architecture

src/test/java/net/bramp/ffmpeg/ExamplesTest.java   ← compilable examples with marker comments
tools/generate_examples.py                          ← extracts markers → EXAMPLES.md
EXAMPLES.md                                         ← generated output (committed to repo)
README.md                                           ← links to EXAMPLES.md

Marker format

// <!-- example:thumbnail title="Extract a Thumbnail" -->
FFmpegBuilder builder = new FFmpegBuilder()
    .setInput("input.mp4")
    .done()
    .addOutput("thumbnail.png")
    ...
    .done();
// <!-- /example -->

The script extracts code between markers into fenced Java blocks under the given title.

Existing ReadmeTest.java

The existing ReadmeTest.java already tests 3 examples (simple encoding, two-pass, HLS). These will get marker comments added and be included in the generated output.

Proposed examples

From README/ReadmeTest (already exist, need markers):

1. Simple video encoding — mp4 with x264/aac, progress listener
2. Two-pass encoding — higher quality encoding
3. Get media information — FFprobe usage
4. HLS multi-variant streaming — adaptive bitrate HLS

From wiki (migrate and clean up):

5. Extract a thumbnail — single frame with scale filter (wiki#3, Get single frames from video source #69, take screens from video #71, create thumbnail from video #107, How To Use FFmpegBuilder Create The Thumb Image #301)
6. Read from RTSP camera — IP camera to jpg (wiki#4, Get image from RTSP (IP camera) #72, Decode rtsp stream #152)
7. Set working directory — custom ProcessFunction (wiki#5, Set process builder's working directory #56, SetWorkingDirectory #110)
8. Create video from images — image sequence input (wiki#6, Images to video #105, Set multiple input images when creating a video #188)
9. Overlay/watermark — complex filter overlay (wiki#7, How add a transparent watermark? #96, Watermark a Video #146, Any Success Example Add watermark #248)
10. HEVC/H.265 transcoding — iOS-compatible output (wiki#8)
11. Adjust volume — audio filter (wiki#12, Get console output of FFMPEG.run command | volume detect #288)

New examples from common issue patterns:

12. Trim/split video by time — -ss and -to (from Divide(split) video to parts  #128, Question for usage extra args for splitting audio #161, How can I extract a part of a video  #169, How to Trim Audio? #185, How to split a video into small chunks and process them separately? #275)
13. Merge/concat videos — concat demuxer (from how to merge some videos #49, Merge Videos #147, How to cut from the end AND how to concat several videos? #199)
14. Extract or remove audio — audio-only output or -an (from AMR to MP3 #136, Extract audio and video #148, Convert any audio to .mp3 #170, Is there a way to remove audio using ffmpeg-cli-wrapper? #286)
15. Add text overlay — drawtext filter (from How can I add any objects (as text or image) to video with this library? #258)
16. MP4 to GIF — format conversion (from MP4 to GIFs #174)
17. Complex filter chains — multiple filters (from setComplexVideoFilter with unexpected results with filtergraph #81, -filter_complex #111, How can I set the filter_complex  #168)
18. Graceful stop — ProcessFunction / Process.destroy() (from Is it possible to interrupt FFMPEG? #158, Kill ffmpeg process? #172, How to stop FFMPEG process gracefully with ffmpeg-cli-wrapper ?  #282, FFmpegJob running. how to do force stop job? #298)
19. Error handling — capturing stderr, handling non-zero exit (from ffprobe returned non-zero exit status. Check stdout. #129, how to catch ffmpeg error? #137, how to catch ffmpeg exception? #232)

Dropped wiki examples (low quality / too niche):

• Wiki#1 (webcam → YouTube RTMP) — very platform-specific, uses dshow
• Wiki#9 (stereo → mono with map_channel) — uses deprecated API patterns
• Wiki#10 (aspect ratio) — messy code with commented-out lines
• Wiki#11 (audio segments to HLS) — covered by HLS example

Tasks

• Add marker comments to ReadmeTest.java (examples 1-4)
• Create ExamplesTest.java with examples 5-19
• Create tools/generate_examples.py
• Generate EXAMPLES.md and commit it
• Add link from README.md to EXAMPLES.md
• Add generation step to CI (or Makefile)
• Deprecate wiki with a note pointing to EXAMPLES.md