Table of contents

GreenScreenVideotoAlphaPNGs: A transparent-frame production pipeline

GreenScreenVideotoAlphaPNGs separates video acquisition, frame extraction and chroma keying from final encoding. RGBA PNG frames are an intermediate output that can feed either the GIF path or an alpha-capable video codec.

Application and tools

Updated 2026-10-23
1
C++ · 57.96%
MIT

Python pytest

View source README Markdown

Languages: 5Code breakdown
Documented components: 2Explore modules
Source documents: 1Read the instructions

Repository languagesC++ 57.96%5

Shares calculated from GitHub Linguist bytes.

C++57.96%

57.96%41,566 bytes

Python32.32%

32.32%23,177 bytes

JavaScript7.93%

7.93%5,687 bytes

PowerShell0.94%

0.94%673 bytes

Language	%	Bytes
C++	57.96%	41,566
Python	32.32%	23,177
JavaScript	7.93%	5,687
PowerShell	0.94%	673
Shell	0.85%	610

GitHub README Language statistics

1. Overview

1.1. Why it exists

OpenCV color-keying pipeline converting chroma-key green videos to RGBA alpha PNG sequences.

1.2. Best fit

Asset preparation for augmented reality (Snapchat Lens Studio, Spark AR).

2. Use cases

A Python CLI that turns green-screen video into transparent PNG frames, GIFs or alpha .mov files for Lens Studio.

People on the left, external systems on the right; each oval is a use case backed by the files cited below.

Download footage from a URL: AR lens creatorYouTube (yt-dlp)
greenscreen convert accepts a YouTube URL; convert.py calls download_video() and download_audio() from download.py, which use yt-dlp.
Split a video into frames: AR lens creatorffmpeg
frames.py writes numbered PNGs (0.png, 1.png…) with ffmpeg, or with OpenCV when --no-ffmpeg is passed.
Key out the green background: AR lens creator
chroma.py computes a YCbCr distance from the key color (pixel 1,1 by default, tolerance 50–130) and writes RGBA PNGs into a sibling *_alpha folder.
Build a transparent GIF: AR lens creatorffmpeg
greenscreen gif <dir> uses numpngw and the optional APNGLib extension by default, or an ffmpeg palette with --fast-ffmpeg; the GIF is written next to the folder.
Encode an alpha .mov: AR lens creatorffmpeg
greenscreen video <dir> --fps 30 encodes the PNG sequence to Videogen-<stamp>.mov with the qtrle or prores_4444 codec.

2.1. Scenario: From a green-screen clip to a Lens Studio animation

Run bash install.sh (or .\install.ps1 on Windows), then uv run greenscreen --help.
Run uv run greenscreen convert clip.mp4 to extract frames into clip/ and keyed frames into clip_alpha/.
Outputs that start with the clip name are moved into project_clip/ unless --no-project-dir is set.
Run uv run greenscreen gif project_clip/clip_alpha --fast-ffmpeg to get a transparent GIF without APNGLib.
In Lens Studio, use Resources → Add New → 2D animation from files and pick the *_alpha PNGs.

Files readREADME.mdpyproject.tomlsrc/greenscreen/cli.pysrc/greenscreen/convert.pysrc/greenscreen/chroma.pysrc/greenscreen/frames.pysrc/greenscreen/gif_pipeline.pysrc/greenscreen/video_pipeline.py

3. Getting started

These commands come from the repository documentation. They were not run during this review.

README.md · Quick start (uv)

.\install.ps1
uv run greenscreen --help

README.md · Quick start (uv)

bash install.sh
uv run greenscreen --help

README.md · APNGLib (optional C++ extension)

$env:SKIP_APNGLIB='1'; uv sync --extra dev

README.md · APNGLib (optional C++ extension)

$env:SKIP_APNGLIB='0'; uv sync --extra dev

4. Repository references

Excerpts from the repository’s guides, in their original language. Links open the inspected source revision.

Prerequisites and first run

4.1. Quick start (uv)

README.md

Install dev tools: uv sync –extra dev

Read the full instructions ↗

4.2. Prerequisites

README.md

Python 3.12+ (repo pins .python-version to 3.12 for uv).
ffmpeg on PATH for fast frame extract and for gif –fast-ffmpeg / video. A fallback binary can come from imageio-ffmpeg if PATH has no ffmpeg.

Read the full instructions ↗

Configuration and usage

4.3. CLI

README.md

Legacy entry points still work and forward to the same CLI:

python GreenVideotoAlphaPNGs.py → greenscreen convert
python GIFGenerator.py → greenscreen gif
python VideoGenerator.py → greenscreen video

Read the full instructions ↗

Source documentation

README.md

1 documents read from 1 candidates.

5. Features and components 2

Conversion stage: The Typer convert command delegates to run_convert. It accepts a local video or URL and can prefer FFmpeg or force OpenCV extraction. The chroma module handles pixel transparency separately from acquisition.
Encoding choices: gif and video take a directory of PNG frames. The GIF path offers an FFmpeg palette option; video accepts qtrle or prores_4444. Encoding is a new stage, so frame rate and format can change without repeating acquisition.

6. Architecture

Expand a component to follow its connections, or explore the full diagram.

System components Context

Video file or URL
- To Frame extraction
Frame extraction
- From Video file or URL
- To Chroma key
Chroma key
- From Frame extraction
- To RGBA PNG sequence
RGBA PNG sequence
- From Chroma key
- To GIF encoder
- To Alpha video encoder
GIF encoder
- From RGBA PNG sequence
Alpha video encoder
- From RGBA PNG sequence

Mermaid Interactive diagram

System overview of the components and connections verified in the repository.

Static architecture view for GreenScreenVideotoAlphaPNGs — Static preview. The interactive diagram replaces it after Mermaid loads.

flowchart LR
  n0["Video file or URL"]
  n1["Frame extraction"]
  n2["Chroma key"]
  n3["RGBA PNG sequence"]
  n4["GIF encoder"]
  n5["Alpha video encoder"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4
  n3 --> n5

Text version of the diagram

Video file or URL → Frame extraction
Frame extraction → Chroma key
Chroma key → RGBA PNG sequence
RGBA PNG sequence → GIF encoder
RGBA PNG sequence → Alpha video encoder

Follow one path through the code

Follow cmd_convert into run_convert, then reuse its PNG output for cmd_video. Preserving the intermediate frames makes it easier to inspect matte edges before compression obscures them.

7. Technical dossier

Built from the source at commit b487e51 (22 files). Each item comes from a pattern match in the code, so open the linked file before relying on it.

7.1. Layers and modules

Folders are sorted into layers by name, from the user interface down to data access. Because the sorting uses names only, the diagram says nothing about calls between layers.

Mermaid Layered view

flowchart TB
  subgraph L_interface["Entry points and API"]
    direction TB
    interface_0["greenscreen<br/>1 file"]
  end
  subgraph L_application["Application services"]
    direction TB
    application_0["TemplatesCutout/Public<br/>4 files"]
    application_1["greenscreen<br/>2 files"]
  end
  subgraph L_infrastructure["Data and infrastructure"]
    direction TB
    infrastructure_0["APNGLib_fix<br/>1 file"]
    infrastructure_1["APNGLib_fix/APNGLib<br/>1 file"]
  end
  subgraph L_core["Core source"]
    direction TB
    core_0["(root)<br/>6 files"]
    core_1["greenscreen<br/>6 files"]
  end
  subgraph L_tests["Tests"]
    direction TB
    tests_0["tests<br/>2 files"]
  end
  L_interface ~~~ L_application
  L_application ~~~ L_infrastructure
  L_infrastructure ~~~ L_core
  L_core ~~~ L_tests

Modules and their main layer
Module	Layer	Files	Types	Extensions
`greenscreen`	Core source	9	0	.py
`(root)`	Core source	6	0	.py .ps1 .sh
`TemplatesCutout/Public`	Application services	4	0	.js
`APNGLib_fix`	Data and infrastructure	1	0	.py
`APNGLib_fix/APNGLib`	Data and infrastructure	1	2	.cpp

7.2. C4 model

From system context to code declarations. Each level reflects the available source evidence.

UML 1 · System context

The widest C4 view: who uses the project and which outside systems and data stores it relies on. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System(SYS, "GreenScreenVideotoAlphaPNGs", "GreenScreenVideotoAlphaPNGs separates video acquisition, frame extrac…")
Rel(P_cli, SYS, "Uses")
@enduml

UML 2 · Containers

One level closer: the parts that run separately inside the project, their main language and how calls flow between them. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Container>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System_Boundary(SYS, "GreenScreenVideotoAlphaPNGs") {
  Container(APP, "GreenScreenVideotoAlphaPNGs", "Python")
}
Rel(P_cli, APP, "Uses")
@enduml

UML 3 · Components and layers

Modules grouped by source-layer classification. Boundaries show organization, not runtime isolation or call relationships. Rendered with uml-mcp.

PlantUML source

@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "GreenScreenVideotoAlphaPNGs") {
Boundary(L0, "Entry points and API", "layer") {
Component(M0_0, "greenscreen", "Python", "1 files")
}
Boundary(L1, "Application services", "layer") {
Component(M1_0, "TemplatesCutout/Public", "JavaScript", "4 files")
Component(M1_1, "greenscreen", "Python", "2 files")
}
Boundary(L2, "Data and infrastructure", "layer") {
Component(M2_0, "APNGLib_fix", "Python", "1 files")
Component(M2_1, "APNGLib_fix/APNGLib", "C++", "1 files")
}
Boundary(L3, "Core source", "layer") {
Component(M3_0, "(root)", "Python, .ps1, .sh", "6 files")
Component(M3_1, "greenscreen", "Python", "6 files")
}
Boundary(L4, "Tests", "layer") {
Component(M4_0, "tests", "Python", "2 files")
}
}
@enduml

UML 4 · Code

Selected declarations, fields and methods grouped by source file. No inheritance or call edges are inferred. Rendered with uml-mcp.

PlantUML source

@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
top to bottom direction
hide empty members
package "GreenScreenVideotoAlphaPNGs" {
package "lib/APNGLib_fix/APNGLib/APNGLib.cpp" as F0 {
class "APNGFrame" as T0_0 {
}
class "CHUNK" as T0_1 {
}
}
object "src/greenscreen/gif_pipeline.py" as FN0 {
  _list_pngs()
  create_gif_apnglib()
  create_gif_ffmpeg()
  create_gif()
}
object "src/greenscreen/cli.py" as FN1 {
  cmd_convert()
  cmd_gif()
  cmd_video()
}
object "src/greenscreen/chroma.py" as FN2 {
  _alpha_from_cb_cr()
  green_screen_rgba()
  remove_green_dir()
}
object "src/greenscreen/convert.py" as FN3 {
  _is_probably_url()
  run_convert()
}
object "src/greenscreen/download.py" as FN4 {
  video_title()
  download_video()
  _hook()
  download_audio()
  _hook()
}
}
@enduml

7.3. Public interface

Outside code can use everything listed here. The project also declares 2 public types.

UML Use cases

Each actor is a kind of caller, linked to what it can ask the project to do. Rendered with uml-mcp.

PlantUML source

@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
left to right direction
actor "CLI user" as A_cli
rectangle "GreenScreenVideotoAlphaPNGs" {
  usecase "Command convert" as U0
  usecase "Command gif" as U1
  usecase "Command video" as U2
}
A_cli --> U0
A_cli --> U1
A_cli --> U2
@enduml

Command line 3

Entry points

greenscreen console script greenscreen.cli:app pyproject.toml

7.4. Private interface

These names are internal by the language’s conventions: a leading underscore, private, static or pub(crate).

underscore helper: 8
static (file-local) function: 2

APNGLib_Decompile lib/APNGLib_fix/APNGLib/APNGLib.cpp:1320
APNGLib_MakeGIF lib/APNGLib_fix/APNGLib/APNGLib.cpp:1357
_libraries lib/APNGLib_fix/setup.py:21
_extension_libraries setup.py:13
_ext_modules setup.py:20

7.5. Entities and data model 2

Mermaid Entity class diagram

classDiagram
  direction LR
  class E0["APNGFrame"] {
  }
  class E1["CHUNK"] {
  }

An arrow links a field to the entity its type names.

Entity	Kind	First fields
`APNGFrame`	Data struct
`CHUNK`	Data struct

7.6. Business logic

No classes were extracted, so these are the largest source files and their functions.

lib/APNGLib_fix/APNGLib/APNGLib.cpp: No named functions.
src/greenscreen/gif_pipeline.py: _list_pngs, create_gif_apnglib, create_gif_ffmpeg, create_gif
src/greenscreen/cli.py: cmd_convert, cmd_gif, cmd_video
src/greenscreen/chroma.py: _alpha_from_cb_cr, green_screen_rgba, remove_green_dir
src/greenscreen/convert.py: _is_probably_url, run_convert
src/greenscreen/download.py: video_title, download_video, _hook, download_audio, _hook

7.7. Stack and dependencies

Python pyproject.toml 11 runtime, 3 dev

Python >=3.12

Open the manifest

External dependencies

14 declared packages (11 runtime, 3 development) in pyproject.toml.

Package table 14

External dependencies
Package	Version	Scope	Purpose	Registry
`typer`	`>=0.12`	runtime	Command line	pypi.org
`rich`	`>=13.7`	runtime	Command line	pypi.org
`tqdm`	`>=4.66`	runtime	Command line	pypi.org
`pillow`	`>=10.0`	runtime	Graphics, imaging and 3D	pypi.org
`numpy`	`>=1.26`	runtime	Data analysis	pypi.org
`opencv-python`	`>=4.9`	runtime	Graphics, imaging and 3D	pypi.org
`natsort`	`>=8.4`	runtime	Simple yet flexible natural sorting in Python.	pypi.org
`imageio`	`>=2.33`	runtime	Graphics, imaging and 3D	pypi.org
`imageio-ffmpeg`	`>=0.4.9`	runtime	Graphics, imaging and 3D	pypi.org
`numpngw`	`>=0.1.2`	runtime	Write numpy array(s) to a PNG or animated PNG file.	pypi.org
`yt-dlp`	`>=2024.1`	runtime	A feature-rich command-line audio/video downloader	pypi.org
`pytest`	`>=8.0`	development	Testing	pypi.org
`pytest-cov`	`>=4.1`	development	Testing	pypi.org
`ruff`	`>=0.8`	development	Linting and formatting	pypi.org

7.8. CI/CD pipeline

No CI/CD pipeline in the repository. The code is built and run by hand, as described above.

7.9. Deployment

Mermaid Deployment diagram

flowchart LR
  repo[("GitHub repository")]
  local["Local machine<br/>Python"]
  repo -->|"clone and run"| local

The repository has no Dockerfile, Compose file or hosting configuration, so the code runs on the machine that clones it.

7.10. Security

Supply chain

Lockfile (pinned dependencies)

Environment variables 1

The page lists names without their values and underlines the ones that look like secrets.

SKIP_APNGLIB

7.11. Testing

Test files: 2
Source files: 21
Test cases, about: 3
Unit tests: 2

pytest

Code coverage

coverage.py

No measured coverage report in the analyzed sources.

Where the tests are

tests 2

Nothing found for: Services, Database, External integrations, Monitoring.

8. Types and file structure

2 declared types, with 2 in the base-relationship overview.

Type diagram

classDiagram
direction TB
class t6f7d26235a07["CHUNK"] {
  <<struct>>
}
class t05c53bd05b93["APNGFrame"] {
  <<struct>>
}

Unresolved bases remain labelled; full signatures are not reconstructed.

9. Reference

21 / 21 eligible files read (45 in the tree); 0 oversized, 0 failed reads and 0 syntax diagnostics.

What the scan covers

Known dependency/build folders, credential files and binaries are excluded. The scan covers READMEs, recognized manifests and parser-supported source files.

Linguist statistics cover the whole repository and may include other languages.

11. Files to read 3

12. Glossary

Repository

The versioned source files, configuration, and history of a project.

README

The repository’s entry document, usually covering its purpose and initial setup.

Dependency

A library, tool, or service that another component needs to build or run.

CLI

A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.

Build

The steps that turn source files and dependencies into a runnable program or distributable artifact.

Video decoder

A component that reconstructs video frames from a compressed stream. Decoding and displaying a frame are separate stages.

13. References

antoinebou12. (2026, November 5). GreenScreenVideotoAlphaPNGs. [Software repository] github.com.
antoinebou12. (2026, November 5). GreenScreenVideotoAlphaPNGs: README. [Repository documentation] github.com.
antoinebou12. (2026, November 5). src/greenscreen/cli.py. [Source file] github.com.
antoinebou12. (2026, November 5). src/greenscreen/chroma.py. [Source file] github.com.
antoinebou12. (2026, November 5). src/greenscreen/video_pipeline.py. [Source file] github.com.
Boucher, A. (2026, October 23). GreenScreenVideotoAlphaPNGs: A transparent-frame production pipeline. [Project article] antoineboucher.info.

Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.