tv-static-gif 0.2.0__tar.gz

tv_static_gif-0.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

tv_static_gif-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/tv-static-gif/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tv_static_gif-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,14 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+      - run: python -m build

tv_static_gif-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+*.gif
+!assets/
+!assets/examples/
+!assets/examples/*.gif
+!assets/examples/*.png

tv_static_gif-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.2.0
+
+- Presets CRT, VHS e sinal fraco.
+- Texto e imagens com velocidade, posição e ajuste automático próprios.
+- Opções de qualidade, escala, cores, loop e formatos GIF, WebP e APNG.
+- CLI com preview, diretório de saída e versão.

tv_static_gif-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fabio Landim Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

tv_static_gif-0.2.0/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: tv-static-gif
+Version: 0.2.0
+Summary: Generate animated TV-static GIFs with Python.
+Project-URL: Homepage, https://github.com/Anderson-Landim/tv-static-gif
+Project-URL: Issues, https://github.com/Anderson-Landim/tv-static-gif/issues
+Author: Your Name
+License: MIT
+License-File: LICENSE
+Keywords: animation,gif,noise,static,television
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tv-static-gif
+
+Biblioteca Python e ferramenta de terminal para criar animações de chiado de TV. Ela gera GIF, WebP animado ou APNG com fundo, texto e logo/imagem em chiado independente.
+
+Por padrão, a animação tem 5 segundos, 820×740 px e 24 fps.
+
+## Instalação
+
+Quando o pacote estiver publicado:
+
+```bash
+pip install tv-static-gif
+```
+
+Para desenvolver neste repositório:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Verifique a instalação:
+
+```bash
+tv-static-gif --version
+tv-static-gif --help
+```
+
+## Início rápido
+
+Crie um GIF simples:
+
+```bash
+tv-static-gif tv.gif
+```
+
+Crie um GIF com texto. O fundo troca a 24 fps e o chiado dentro das letras troca a 6 fps:
+
+```bash
+tv-static-gif tv.gif --text "TV" --font-size 280 --background-fps 24 --text-fps 6
+```
+
+O mesmo exemplo em Python:
+
+```python
+from tv_static_gif import generate_tv_static
+
+generate_tv_static(
+    "tv.gif",
+    text="TV",
+    font_size=280,
+    background_fps=24,
+    text_fps=6,
+)
+```
+
+## Conceitos principais
+
+`fps` é a taxa de reprodução do arquivo. `background_fps`, `text_fps` e `image_fps` controlam com que frequência cada chiado é trocado e devem ser menores ou iguais a `fps`.
+
+Texto e imagens não recebem uma cor sólida: eles usam o mesmo chiado cinza de pixels 1×1 do fundo, só com uma velocidade independente. Isso permite que as letras apareçam pelo movimento diferente da estática.
+
+## Exemplos visuais
+
+### CRT com texto lento
+
+Fundo a 12 fps e texto a 3 fps, com linhas de varredura do preset `crt`.
+
+![Exemplo CRT com texto TV](assets/examples/crt-text.gif)
+
+### Sinal fraco com marca
+
+O preset `weak-signal` combina tremor, cintilação e interferência. A marca no canto inferior usa uma máscara PNG e seu próprio ritmo de chiado.
+
+![Exemplo de sinal fraco com marca](assets/examples/weak-signal-logo.gif)
+
+## Linha de comando
+
+Formato geral:
+
+```bash
+tv-static-gif SAIDA [opções]
+```
+
+### Todos os parâmetros
+
+| Opção                        | Padrão                | Descrição                                                      |
+| ------------------------------ | ---------------------- | ---------------------------------------------------------------- |
+| `output`                     | obrigatório           | Caminho do arquivo de saída.                                    |
+| `--version`                  | —                     | Mostra a versão instalada.                                      |
+| `--width N`                  | `820`                | Largura original em pixels.                                      |
+| `--height N`                 | `740`                | Altura original em pixels.                                       |
+| `--duration N`               | `5`                  | Duração em segundos.                                           |
+| `--fps N`                    | `24`                 | FPS de reprodução; de 1 a 100.                                 |
+| `--background-fps N`         | igual a`--fps`       | Velocidade de troca do fundo.                                    |
+| `--text TEXTO`               | —                     | Texto renderizado como chiado.                                   |
+| `--text-fps N`               | `6`                  | Velocidade de troca do chiado no texto.                          |
+| `--font ARQUIVO`             | fonte do sistema       | Fonte`.ttf` ou `.otf`.                                       |
+| `--font-size N`              | `220`                | Tamanho da fonte em pixels.                                      |
+| `--text-position POSIÇÃO`  | `center`             | `top`, `center` ou `bottom`.                               |
+| `--no-auto-fit`              | desligado              | Não reduz a fonte automaticamente quando o texto não cabe.     |
+| `--image ARQUIVO`            | —                     | PNG/imagem com transparência usada como máscara de chiado.     |
+| `--image-fps N`              | igual a`--text-fps`  | Velocidade do chiado da imagem.                                  |
+| `--image-position POSIÇÃO` | `bottom`             | `top`, `center` ou `bottom`.                               |
+| `--image-scale N`            | `0.25`               | Fração máxima do quadro usada pela imagem.                    |
+| `--preset NOME`              | `crt`                | `clean`, `crt`, `weak-signal` ou `vhs`.                  |
+| `--quality NÍVEL`           | `high`               | `low`, `medium` ou `high`. Define escala e cores.          |
+| `--scale N`                  | definido por qualidade | Escala final do quadro;`0.5` produz metade da largura/altura.  |
+| `--colors N`                 | definido por qualidade | Número de tons de cinza, de 2 a 256.                            |
+| `--format FORMATO`           | pela extensão         | `gif`, `webp` ou `apng`.                                   |
+| `--loop N`                   | `0`                  | Repetições;`0` significa repetir infinitamente.              |
+| `--output-dir PASTA`         | —                     | Pasta de destino; preserva apenas o nome informado em`output`. |
+| `--seed N`                   | aleatória             | Semente para reproduzir a mesma animação.                      |
+| `--preview`                  | desligado              | Abre o arquivo quando a geração termina.                       |
+
+### Exemplos de terminal
+
+GIF de 10 segundos em resolução personalizada:
+
+```bash
+tv-static-gif chiado.gif --width 1280 --height 720 --duration 10 --fps 30
+```
+
+Fundo veloz e texto lento:
+
+```bash
+tv-static-gif tv.gif --text "SEM SINAL" --fps 24 --background-fps 24 --text-fps 4
+```
+
+Texto embaixo, com fonte escolhida:
+
+```powershell
+tv-static-gif tv.gif --text "AO VIVO" --font "C:/Windows/Fonts/arialbd.ttf" --font-size 150 --text-position bottom
+```
+
+Logo PNG no topo, com velocidade separada:
+
+```bash
+tv-static-gif tv.gif --image logo.png --image-position top --image-scale 0.2 --image-fps 8
+```
+
+Efeito de sinal fraco:
+
+```bash
+tv-static-gif sinal.gif --preset weak-signal --text "SEM SINAL" --text-fps 3
+```
+
+Efeito VHS e arquivo menor:
+
+```bash
+tv-static-gif fita.webp --format webp --preset vhs --quality medium --text "VHS"
+```
+
+APNG com poucos tons de cinza:
+
+```bash
+tv-static-gif chiado.png --format apng --quality low --colors 32
+```
+
+Metade da resolução, com duas repetições:
+
+```bash
+tv-static-gif pequeno.gif --scale 0.5 --loop 2
+```
+
+Salvar numa pasta e abrir após gerar:
+
+```bash
+tv-static-gif tv.gif --output-dir ./gifs --preview
+```
+
+Gerar a mesma animação novamente:
+
+```bash
+tv-static-gif teste.gif --seed 42 --text "TESTE"
+```
+
+## API Python
+
+Há duas funções públicas:
+
+```python
+from tv_static_gif import generate_tv_static, generate_tv_static_gif
+```
+
+- `generate_tv_static(...)`: cria GIF, WebP ou APNG.
+- `generate_tv_static_gif(...)`: compatível com versões antigas; sempre cria GIF.
+
+### Assinatura completa
+
+```python
+generate_tv_static(
+    output,
+    width=820, height=740, duration=5, fps=24,
+    background_fps=None,
+    text=None, text_fps=6, font_path=None, font_size=220,
+    text_position="center", auto_fit=True,
+    image_path=None, image_fps=None, image_position="bottom", image_scale=0.25,
+    preset="crt", quality="high", scale=None, colors=None,
+    output_format=None, loop=0, seed=None, progress=None,
+)
+```
+
+| Parâmetro                                      | Descrição                                                                 |
+| ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `output`                                      | Caminho do arquivo criado. A extensão pode definir o formato.              |
+| `width`, `height`, `duration`, `fps`    | Dimensões, duração e taxa de reprodução.                               |
+| `background_fps`, `text_fps`, `image_fps` | Velocidade de atualização do chiado em cada camada.                       |
+| `text`, `font_path`, `font_size`          | Conteúdo e estilo do texto.                                                |
+| `text_position`, `image_position`           | `top`, `center` ou `bottom`.                                          |
+| `auto_fit`                                    | Ajusta o texto horizontalmente para caber no quadro.                        |
+| `image_path`, `image_scale`                 | Imagem usada como máscara e seu tamanho máximo proporcional.              |
+| `preset`                                      | `clean`, `crt`, `weak-signal` ou `vhs`.                             |
+| `quality`                                     | `low` = 50%/64 tons; `medium` = 75%/128 tons; `high` = 100%/256 tons. |
+| `scale`, `colors`                           | Sobrescrevem a escala e os tons definidos pela qualidade.                   |
+| `output_format`                               | `gif`, `webp` ou `apng`; quando `None`, usa a extensão.            |
+| `loop`                                        | Número de repetições;`0` é infinito.                                  |
+| `seed`                                        | Inteiro para resultado reproduzível.                                       |
+| `progress`                                    | Função opcional chamada como`progress(quadro_atual, total_de_quadros)`. |
+
+### Exemplos em Python
+
+GIF simples:
+
+```python
+from tv_static_gif import generate_tv_static_gif
+
+path = generate_tv_static_gif("chiado.gif")
+print(path)
+```
+
+WebP com todas as camadas:
+
+```python
+from tv_static_gif import generate_tv_static
+
+generate_tv_static(
+    "sinal.webp",
+    output_format="webp",
+    preset="vhs",
+    quality="medium",
+    text="AO VIVO",
+    text_position="top",
+    text_fps=5,
+    background_fps=24,
+    image_path="logo.png",
+    image_position="bottom",
+    image_fps=8,
+)
+```
+
+Usando progresso:
+
+```python
+from tv_static_gif import generate_tv_static
+
+def progresso(atual, total):
+    print(f"Quadro {atual}/{total}")
+
+generate_tv_static("progresso.gif", text="TV", progress=progresso)
+```
+
+## Presets
+
+- `clean`: apenas ruído cinza, sem efeitos extras.
+- `crt`: linhas de varredura, pequena oscilação e cintilação leve.
+- `weak-signal`: cintilação, tremor e faixas de interferência mais fortes.
+- `vhs`: efeito de fita com linhas, tremor e glitches horizontais.
+
+## Tamanho de arquivo e desempenho
+
+Ruído aleatório comprime pouco. GIFs de 820×740 px, 24 fps e 5 segundos podem ser grandes. Para reduzir o arquivo, prefira `--quality medium`, `--quality low`, `--scale 0.5`, menos duração ou WebP animado.
+
+## Desenvolvimento, testes e PyPI
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+python -m build
+twine check dist/*
+```
+
+O workflow em `.github/workflows/tests.yml` executa testes e build no GitHub Actions. Antes de publicar, troque o autor e as URLs em `pyproject.toml`, reserve o nome no PyPI e use:
+
+```bash
+twine upload dist/*
+```
+
+## Licença
+
+MIT. Veja [LICENSE](LICENSE).

tv_static_gif-0.2.0/README.md

@@ -0,0 +1,290 @@
+# tv-static-gif
+
+Biblioteca Python e ferramenta de terminal para criar animações de chiado de TV. Ela gera GIF, WebP animado ou APNG com fundo, texto e logo/imagem em chiado independente.
+
+Por padrão, a animação tem 5 segundos, 820×740 px e 24 fps.
+
+## Instalação
+
+Quando o pacote estiver publicado:
+
+```bash
+pip install tv-static-gif
+```
+
+Para desenvolver neste repositório:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Verifique a instalação:
+
+```bash
+tv-static-gif --version
+tv-static-gif --help
+```
+
+## Início rápido
+
+Crie um GIF simples:
+
+```bash
+tv-static-gif tv.gif
+```
+
+Crie um GIF com texto. O fundo troca a 24 fps e o chiado dentro das letras troca a 6 fps:
+
+```bash
+tv-static-gif tv.gif --text "TV" --font-size 280 --background-fps 24 --text-fps 6
+```
+
+O mesmo exemplo em Python:
+
+```python
+from tv_static_gif import generate_tv_static
+
+generate_tv_static(
+    "tv.gif",
+    text="TV",
+    font_size=280,
+    background_fps=24,
+    text_fps=6,
+)
+```
+
+## Conceitos principais
+
+`fps` é a taxa de reprodução do arquivo. `background_fps`, `text_fps` e `image_fps` controlam com que frequência cada chiado é trocado e devem ser menores ou iguais a `fps`.
+
+Texto e imagens não recebem uma cor sólida: eles usam o mesmo chiado cinza de pixels 1×1 do fundo, só com uma velocidade independente. Isso permite que as letras apareçam pelo movimento diferente da estática.
+
+## Exemplos visuais
+
+### CRT com texto lento
+
+Fundo a 12 fps e texto a 3 fps, com linhas de varredura do preset `crt`.
+
+![Exemplo CRT com texto TV](assets/examples/crt-text.gif)
+
+### Sinal fraco com marca
+
+O preset `weak-signal` combina tremor, cintilação e interferência. A marca no canto inferior usa uma máscara PNG e seu próprio ritmo de chiado.
+
+![Exemplo de sinal fraco com marca](assets/examples/weak-signal-logo.gif)
+
+## Linha de comando
+
+Formato geral:
+
+```bash
+tv-static-gif SAIDA [opções]
+```
+
+### Todos os parâmetros
+
+| Opção                        | Padrão                | Descrição                                                      |
+| ------------------------------ | ---------------------- | ---------------------------------------------------------------- |
+| `output`                     | obrigatório           | Caminho do arquivo de saída.                                    |
+| `--version`                  | —                     | Mostra a versão instalada.                                      |
+| `--width N`                  | `820`                | Largura original em pixels.                                      |
+| `--height N`                 | `740`                | Altura original em pixels.                                       |
+| `--duration N`               | `5`                  | Duração em segundos.                                           |
+| `--fps N`                    | `24`                 | FPS de reprodução; de 1 a 100.                                 |
+| `--background-fps N`         | igual a`--fps`       | Velocidade de troca do fundo.                                    |
+| `--text TEXTO`               | —                     | Texto renderizado como chiado.                                   |
+| `--text-fps N`               | `6`                  | Velocidade de troca do chiado no texto.                          |
+| `--font ARQUIVO`             | fonte do sistema       | Fonte`.ttf` ou `.otf`.                                       |
+| `--font-size N`              | `220`                | Tamanho da fonte em pixels.                                      |
+| `--text-position POSIÇÃO`  | `center`             | `top`, `center` ou `bottom`.                               |
+| `--no-auto-fit`              | desligado              | Não reduz a fonte automaticamente quando o texto não cabe.     |
+| `--image ARQUIVO`            | —                     | PNG/imagem com transparência usada como máscara de chiado.     |
+| `--image-fps N`              | igual a`--text-fps`  | Velocidade do chiado da imagem.                                  |
+| `--image-position POSIÇÃO` | `bottom`             | `top`, `center` ou `bottom`.                               |
+| `--image-scale N`            | `0.25`               | Fração máxima do quadro usada pela imagem.                    |
+| `--preset NOME`              | `crt`                | `clean`, `crt`, `weak-signal` ou `vhs`.                  |
+| `--quality NÍVEL`           | `high`               | `low`, `medium` ou `high`. Define escala e cores.          |
+| `--scale N`                  | definido por qualidade | Escala final do quadro;`0.5` produz metade da largura/altura.  |
+| `--colors N`                 | definido por qualidade | Número de tons de cinza, de 2 a 256.                            |
+| `--format FORMATO`           | pela extensão         | `gif`, `webp` ou `apng`.                                   |
+| `--loop N`                   | `0`                  | Repetições;`0` significa repetir infinitamente.              |
+| `--output-dir PASTA`         | —                     | Pasta de destino; preserva apenas o nome informado em`output`. |
+| `--seed N`                   | aleatória             | Semente para reproduzir a mesma animação.                      |
+| `--preview`                  | desligado              | Abre o arquivo quando a geração termina.                       |
+
+### Exemplos de terminal
+
+GIF de 10 segundos em resolução personalizada:
+
+```bash
+tv-static-gif chiado.gif --width 1280 --height 720 --duration 10 --fps 30
+```
+
+Fundo veloz e texto lento:
+
+```bash
+tv-static-gif tv.gif --text "SEM SINAL" --fps 24 --background-fps 24 --text-fps 4
+```
+
+Texto embaixo, com fonte escolhida:
+
+```powershell
+tv-static-gif tv.gif --text "AO VIVO" --font "C:/Windows/Fonts/arialbd.ttf" --font-size 150 --text-position bottom
+```
+
+Logo PNG no topo, com velocidade separada:
+
+```bash
+tv-static-gif tv.gif --image logo.png --image-position top --image-scale 0.2 --image-fps 8
+```
+
+Efeito de sinal fraco:
+
+```bash
+tv-static-gif sinal.gif --preset weak-signal --text "SEM SINAL" --text-fps 3
+```
+
+Efeito VHS e arquivo menor:
+
+```bash
+tv-static-gif fita.webp --format webp --preset vhs --quality medium --text "VHS"
+```
+
+APNG com poucos tons de cinza:
+
+```bash
+tv-static-gif chiado.png --format apng --quality low --colors 32
+```
+
+Metade da resolução, com duas repetições:
+
+```bash
+tv-static-gif pequeno.gif --scale 0.5 --loop 2
+```
+
+Salvar numa pasta e abrir após gerar:
+
+```bash
+tv-static-gif tv.gif --output-dir ./gifs --preview
+```
+
+Gerar a mesma animação novamente:
+
+```bash
+tv-static-gif teste.gif --seed 42 --text "TESTE"
+```
+
+## API Python
+
+Há duas funções públicas:
+
+```python
+from tv_static_gif import generate_tv_static, generate_tv_static_gif
+```
+
+- `generate_tv_static(...)`: cria GIF, WebP ou APNG.
+- `generate_tv_static_gif(...)`: compatível com versões antigas; sempre cria GIF.
+
+### Assinatura completa
+
+```python
+generate_tv_static(
+    output,
+    width=820, height=740, duration=5, fps=24,
+    background_fps=None,
+    text=None, text_fps=6, font_path=None, font_size=220,
+    text_position="center", auto_fit=True,
+    image_path=None, image_fps=None, image_position="bottom", image_scale=0.25,
+    preset="crt", quality="high", scale=None, colors=None,
+    output_format=None, loop=0, seed=None, progress=None,
+)
+```
+
+| Parâmetro                                      | Descrição                                                                 |
+| ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `output`                                      | Caminho do arquivo criado. A extensão pode definir o formato.              |
+| `width`, `height`, `duration`, `fps`    | Dimensões, duração e taxa de reprodução.                               |
+| `background_fps`, `text_fps`, `image_fps` | Velocidade de atualização do chiado em cada camada.                       |
+| `text`, `font_path`, `font_size`          | Conteúdo e estilo do texto.                                                |
+| `text_position`, `image_position`           | `top`, `center` ou `bottom`.                                          |
+| `auto_fit`                                    | Ajusta o texto horizontalmente para caber no quadro.                        |
+| `image_path`, `image_scale`                 | Imagem usada como máscara e seu tamanho máximo proporcional.              |
+| `preset`                                      | `clean`, `crt`, `weak-signal` ou `vhs`.                             |
+| `quality`                                     | `low` = 50%/64 tons; `medium` = 75%/128 tons; `high` = 100%/256 tons. |
+| `scale`, `colors`                           | Sobrescrevem a escala e os tons definidos pela qualidade.                   |
+| `output_format`                               | `gif`, `webp` ou `apng`; quando `None`, usa a extensão.            |
+| `loop`                                        | Número de repetições;`0` é infinito.                                  |
+| `seed`                                        | Inteiro para resultado reproduzível.                                       |
+| `progress`                                    | Função opcional chamada como`progress(quadro_atual, total_de_quadros)`. |
+
+### Exemplos em Python
+
+GIF simples:
+
+```python
+from tv_static_gif import generate_tv_static_gif
+
+path = generate_tv_static_gif("chiado.gif")
+print(path)
+```
+
+WebP com todas as camadas:
+
+```python
+from tv_static_gif import generate_tv_static
+
+generate_tv_static(
+    "sinal.webp",
+    output_format="webp",
+    preset="vhs",
+    quality="medium",
+    text="AO VIVO",
+    text_position="top",
+    text_fps=5,
+    background_fps=24,
+    image_path="logo.png",
+    image_position="bottom",
+    image_fps=8,
+)
+```
+
+Usando progresso:
+
+```python
+from tv_static_gif import generate_tv_static
+
+def progresso(atual, total):
+    print(f"Quadro {atual}/{total}")
+
+generate_tv_static("progresso.gif", text="TV", progress=progresso)
+```
+
+## Presets
+
+- `clean`: apenas ruído cinza, sem efeitos extras.
+- `crt`: linhas de varredura, pequena oscilação e cintilação leve.
+- `weak-signal`: cintilação, tremor e faixas de interferência mais fortes.
+- `vhs`: efeito de fita com linhas, tremor e glitches horizontais.
+
+## Tamanho de arquivo e desempenho
+
+Ruído aleatório comprime pouco. GIFs de 820×740 px, 24 fps e 5 segundos podem ser grandes. Para reduzir o arquivo, prefira `--quality medium`, `--quality low`, `--scale 0.5`, menos duração ou WebP animado.
+
+## Desenvolvimento, testes e PyPI
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+python -m build
+twine check dist/*
+```
+
+O workflow em `.github/workflows/tests.yml` executa testes e build no GitHub Actions. Antes de publicar, troque o autor e as URLs em `pyproject.toml`, reserve o nome no PyPI e use:
+
+```bash
+twine upload dist/*
+```
+
+## Licença
+
+MIT. Veja [LICENSE](LICENSE).

tv_static_gif-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tv-static-gif"
+version = "0.2.0"
+description = "Generate animated TV-static GIFs with Python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Your Name" }]
+keywords = ["gif", "television", "static", "noise", "animation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  
+]
+dependencies = ["Pillow>=10.0"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/Anderson-Landim/tv-static-gif"
+Issues = "https://github.com/Anderson-Landim/tv-static-gif/issues"
+
+[project.scripts]
+tv-static-gif = "tv_static_gif.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tv_static_gif"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tv_static_gif-0.2.0/release.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tv-static-gif
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tv_static_gif-0.2.0/src/tv_static_gif/__init__.py

@@ -0,0 +1,6 @@
+"""Create animated GIFs that resemble analog television static."""
+
+from .generator import generate_tv_static, generate_tv_static_gif
+
+__all__ = ["generate_tv_static", "generate_tv_static_gif"]
+__version__ = "0.2.0"

tv_static_gif-0.2.0/src/tv_static_gif/cli.py

@@ -0,0 +1,34 @@
+"""Command-line interface."""
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+import webbrowser
+
+from . import __version__
+from .generator import PRESETS, QUALITY, generate_tv_static
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate animated TV static.")
+    parser.add_argument("output")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--width", type=int, default=820); parser.add_argument("--height", type=int, default=740)
+    parser.add_argument("--duration", type=float, default=5); parser.add_argument("--fps", type=int, default=24)
+    parser.add_argument("--background-fps", type=int); parser.add_argument("--text", default=None); parser.add_argument("--text-fps", type=int, default=6)
+    parser.add_argument("--font"); parser.add_argument("--font-size", type=int, default=220); parser.add_argument("--text-position", choices=("top", "center", "bottom"), default="center")
+    parser.add_argument("--no-auto-fit", action="store_true"); parser.add_argument("--image"); parser.add_argument("--image-fps", type=int); parser.add_argument("--image-position", choices=("top", "center", "bottom"), default="bottom"); parser.add_argument("--image-scale", type=float, default=.25)
+    parser.add_argument("--preset", choices=tuple(PRESETS), default="crt"); parser.add_argument("--quality", choices=tuple(QUALITY), default="high"); parser.add_argument("--scale", type=float); parser.add_argument("--colors", type=int)
+    parser.add_argument("--format", dest="output_format", choices=("gif", "webp", "apng")); parser.add_argument("--loop", type=int, default=0); parser.add_argument("--output-dir", type=Path); parser.add_argument("--seed", type=int); parser.add_argument("--preview", action="store_true")
+    args = parser.parse_args()
+    output = (args.output_dir / Path(args.output).name) if args.output_dir else Path(args.output)
+    params = vars(args); params.pop("output"); params.pop("output_dir"); preview = params.pop("preview"); params["font_path"] = params.pop("font"); params["image_path"] = params.pop("image"); params["auto_fit"] = not params.pop("no_auto_fit")
+    path = generate_tv_static(output, **params)
+    print(f"Created: {path}")
+    if preview:
+        if hasattr(os, "startfile"): os.startfile(path)  # type: ignore[attr-defined]
+        else: webbrowser.open(path.resolve().as_uri())
+
+
+if __name__ == "__main__": main()

tv_static_gif-0.2.0/src/tv_static_gif/generator.py

@@ -0,0 +1,192 @@
+"""Create animated TV-static files."""
+
+from __future__ import annotations
+
+import random
+from pathlib import Path
+from typing import Callable, Optional, Union
+
+from PIL import Image, ImageChops, ImageDraw, ImageFont
+
+PathLike = Union[str, Path]
+ProgressCallback = Callable[[int, int], None]
+
+PRESETS = {
+    "clean": {"scanlines": 0, "flicker": 0, "jitter": 0, "glitch": 0},
+    "crt": {"scanlines": 4, "flicker": 8, "jitter": 1, "glitch": 0},
+    "weak-signal": {"scanlines": 3, "flicker": 24, "jitter": 3, "glitch": 3},
+    "vhs": {"scanlines": 4, "flicker": 14, "jitter": 2, "glitch": 8},
+}
+QUALITY = {"low": (0.5, 64), "medium": (0.75, 128), "high": (1.0, 256)}
+
+
+def _font(path: Optional[PathLike], size: int) -> ImageFont.ImageFont:
+    if path is not None:
+        try:
+            return ImageFont.truetype(str(path), size)
+        except OSError as error:
+            raise ValueError(f"could not load font: {path}") from error
+    for name in ("DejaVuSans-Bold.ttf", "Arial.ttf", "arial.ttf"):
+        try:
+            return ImageFont.truetype(name, size)
+        except OSError:
+            pass
+    return ImageFont.load_default()
+
+
+def _position(size: tuple[int, int], content: tuple[int, int], where: str) -> tuple[int, int]:
+    width, height = size
+    content_width, content_height = content
+    x = (width - content_width) // 2
+    if where == "top":
+        return x, max(0, height // 20)
+    if where == "bottom":
+        return x, max(0, height - content_height - height // 20)
+    return x, (height - content_height) // 2
+
+
+def _text_mask(
+    size: tuple[int, int], text: Optional[str], font_path: Optional[PathLike],
+    font_size: int, position: str, auto_fit: bool,
+) -> Optional[Image.Image]:
+    if not text:
+        return None
+    font = _font(font_path, font_size)
+    probe = ImageDraw.Draw(Image.new("L", (1, 1)))
+    box = probe.multiline_textbbox((0, 0), text, font=font, align="center")
+    if auto_fit and box[2] - box[0] > size[0] * 0.9 and font_size > 8:
+        font = _font(font_path, max(8, int(font_size * size[0] * 0.9 / (box[2] - box[0]))))
+        box = probe.multiline_textbbox((0, 0), text, font=font, align="center")
+    mask = Image.new("L", size)
+    draw = ImageDraw.Draw(mask)
+    xy = _position(size, (box[2] - box[0], box[3] - box[1]), position)
+    draw.multiline_text((xy[0] - box[0], xy[1] - box[1]), text, font=font, fill=255, align="center")
+    return mask
+
+
+def _image_mask(path: Optional[PathLike], size: tuple[int, int], position: str, scale: float) -> Optional[Image.Image]:
+    if path is None:
+        return None
+    try:
+        source = Image.open(path).convert("RGBA")
+    except OSError as error:
+        raise ValueError(f"could not load image: {path}") from error
+    max_size = (max(1, int(size[0] * scale)), max(1, int(size[1] * scale)))
+    source.thumbnail(max_size, Image.Resampling.LANCZOS)
+    mask = Image.new("L", size)
+    mask.paste(source.getchannel("A"), _position(size, source.size, position))
+    return mask
+
+
+def _pattern(size: tuple[int, int], rng: random.Random, preset: dict[str, int], colors: int) -> Image.Image:
+    width, height = size
+    pixels = bytearray(rng.randbytes(width * height))
+    if colors < 256:
+        step = 256 // colors
+        for index, value in enumerate(pixels):
+            pixels[index] = (value // step) * step
+    step = preset["scanlines"]
+    if step:
+        for y in range(0, height, step):
+            start, end = y * width, (y + 1) * width
+            pixels[start:end] = bytes(value // 2 for value in pixels[start:end])
+    image = Image.frombytes("L", size, bytes(pixels))
+    if preset["flicker"]:
+        image = ImageChops.subtract(image, Image.new("L", size, rng.randrange(preset["flicker"])))
+    if preset["jitter"]:
+        image = ImageChops.offset(image, rng.randrange(-preset["jitter"], preset["jitter"] + 1), 0)
+    if preset["glitch"]:
+        for _ in range(2):
+            y = rng.randrange(height)
+            band = image.crop((0, y, width, min(height, y + rng.randrange(1, preset["glitch"] + 1))))
+            image.paste(ImageChops.offset(band, rng.randrange(-preset["glitch"], preset["glitch"] + 1), 0), (0, y))
+    return image
+
+
+def _format(destination: Path, requested: Optional[str]) -> tuple[Path, str]:
+    aliases = {"gif": (".gif", "GIF"), "webp": (".webp", "WEBP"), "apng": (".png", "PNG")}
+    key = (requested or {".webp": "webp", ".png": "apng"}.get(destination.suffix.lower(), "gif")).lower()
+    if key not in aliases:
+        raise ValueError("output_format must be gif, webp or apng")
+    suffix, pillow_format = aliases[key]
+    return destination.with_suffix(suffix), pillow_format
+
+
+def generate_tv_static(
+    output: PathLike, *, width: int = 820, height: int = 740, duration: float = 5,
+    fps: int = 24, background_fps: Optional[int] = None, text: Optional[str] = None,
+    text_fps: int = 6, font_path: Optional[PathLike] = None, font_size: int = 220,
+    text_position: str = "center", auto_fit: bool = True, image_path: Optional[PathLike] = None,
+    image_fps: Optional[int] = None, image_position: str = "bottom", image_scale: float = 0.25,
+    preset: str = "crt", quality: str = "high", scale: Optional[float] = None,
+    colors: Optional[int] = None, output_format: Optional[str] = None, loop: int = 0,
+    seed: Optional[int] = None, progress: Optional[ProgressCallback] = None,
+) -> Path:
+    """Generate TV static in GIF, animated WebP, or APNG format."""
+    if width < 1 or height < 1 or duration <= 0 or not 1 <= fps <= 100:
+        raise ValueError("width/height must be positive, duration positive, and fps between 1 and 100")
+    if preset not in PRESETS or quality not in QUALITY:
+        raise ValueError(f"preset must be one of {', '.join(PRESETS)}; quality must be one of {', '.join(QUALITY)}")
+    if text_position not in {"top", "center", "bottom"} or image_position not in {"top", "center", "bottom"}:
+        raise ValueError("positions must be top, center or bottom")
+    if not 1 <= text_fps <= fps or (image_fps is not None and not 1 <= image_fps <= fps):
+        raise ValueError("text_fps and image_fps must be between 1 and fps")
+    bg_fps = background_fps or fps
+    if not 1 <= bg_fps <= fps or font_size < 1 or image_scale <= 0 or loop < 0:
+        raise ValueError("invalid speed, font_size, image_scale or loop")
+    quality_scale, quality_colors = QUALITY[quality]
+    actual_scale = quality_scale if scale is None else scale
+    if actual_scale <= 0:
+        raise ValueError("scale must be positive")
+    size = (max(1, round(width * actual_scale)), max(1, round(height * actual_scale)))
+    palette_colors = quality_colors if colors is None else colors
+    if not 2 <= palette_colors <= 256:
+        raise ValueError("colors must be between 2 and 256")
+    destination, pillow_format = _format(Path(output), output_format)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    text_mask = _text_mask(size, text, font_path, max(1, round(font_size * actual_scale)), text_position, auto_fit)
+    image_mask = _image_mask(image_path, size, image_position, image_scale)
+    count, rng = max(1, round(duration * fps)), random.Random(seed)
+    durations = [((index + 1) * round(duration * 100) // count - index * round(duration * 100) // count) * 10 for index in range(count)]
+    current_bg = current_text = current_image = None
+    seen_bg = seen_text = seen_image = -1
+    frames: list[Image.Image] = []
+    for index in range(count):
+        key = index * bg_fps // fps
+        if key != seen_bg:
+            current_bg, seen_bg = _pattern(size, rng, PRESETS[preset], palette_colors), key
+        if text_mask is not None and index * text_fps // fps != seen_text:
+            current_text, seen_text = _pattern(size, rng, PRESETS[preset], palette_colors), index * text_fps // fps
+        effective_image_fps = image_fps or text_fps
+        if image_mask is not None and index * effective_image_fps // fps != seen_image:
+            current_image, seen_image = _pattern(size, rng, PRESETS[preset], palette_colors), index * effective_image_fps // fps
+        frame = current_bg.copy()
+        if text_mask is not None and current_text is not None:
+            frame = Image.composite(current_text, frame, text_mask)
+        if image_mask is not None and current_image is not None:
+            frame = Image.composite(current_image, frame, image_mask)
+        frames.append(frame)
+        if progress:
+            progress(index + 1, count)
+    save_frames = [frame.convert("P", colors=palette_colors) if pillow_format == "GIF" else frame for frame in frames]
+    save_options = {
+        "format": pillow_format,
+        "save_all": True,
+        "append_images": save_frames[1:],
+        "duration": durations,
+        "loop": loop,
+    }
+    if pillow_format == "GIF":
+        save_options.update({"optimize": False, "disposal": 2})
+    elif pillow_format == "WEBP":
+        save_options.update({"lossless": True, "method": 6})
+    else:  # APNG
+        save_options.update({"disposal": 0, "blend": 0})
+    save_frames[0].save(destination, **save_options)
+    return destination
+
+
+def generate_tv_static_gif(output: PathLike, **kwargs: object) -> Path:
+    """Backward-compatible GIF-only wrapper around :func:`generate_tv_static`."""
+    kwargs["output_format"] = "gif"
+    return generate_tv_static(output, **kwargs)  # type: ignore[arg-type]

tv_static_gif-0.2.0/tests/test_generator.py

@@ -0,0 +1,29 @@
+from PIL import Image
+import pytest
+
+from tv_static_gif import generate_tv_static_gif
+
+
+def test_generates_five_second_gif(tmp_path):
+    output = generate_tv_static_gif(
+        tmp_path / "static", width=82, height=74, fps=24, text="TV", font_size=24
+    )
+
+    assert output.name == "static.gif"
+    with Image.open(output) as gif:
+        assert gif.format == "GIF"
+        assert gif.size == (82, 74)
+        assert gif.n_frames == 120
+        assert sum(
+            (gif.seek(frame), gif.info["duration"])[1]
+            for frame in range(gif.n_frames)
+        ) == 5000
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [{"width": 0}, {"height": 0}, {"duration": 0}, {"fps": 0}],
+)
+def test_rejects_invalid_settings(tmp_path, kwargs):
+    with pytest.raises(ValueError):
+        generate_tv_static_gif(tmp_path / "static.gif", **kwargs)