Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@ permissions:

jobs:
test:
runs-on: windows-latest
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
python-version: ["3.11", "3.12"]
steps:
- uses: actions/checkout@v4
Expand Down
81 changes: 81 additions & 0 deletions .github/workflows/linux-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
name: Linux executable

on:
pull_request:
paths:
- "app/**"
- "migrations/**"
- "linux/**"
- "LICENSE"
- "alembic.ini"
- "pyproject.toml"
- ".github/workflows/linux-release.yml"
release:
types: [published]
workflow_dispatch:

permissions:
contents: read

jobs:
build:
runs-on: ubuntu-22.04
permissions:
contents: write
id-token: write
attestations: write
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
cache-dependency-path: pyproject.toml

- name: Install dependencies
run: python -m pip install -e ".[build]"

- name: Read the version
id: version
shell: bash
run: |
version="$(python -c 'import app; print(app.__version__)')"
echo "version=$version" >> "$GITHUB_OUTPUT"
if [[ "${{ github.event_name }}" == release ]]; then
tag="${{ github.event.release.tag_name }}"
if [[ "$tag" != "v$version" ]]; then
echo "Release tag $tag does not match app.__version__ $version" >&2
exit 1
fi
fi

- name: Build
run: python linux/build.py

- name: Smoke test
run: python linux/smoke_test.py --expect-version "${{ steps.version.outputs.version }}"

- uses: actions/upload-artifact@v4
with:
name: AceList-${{ steps.version.outputs.version }}-linux-x86_64
path: |
dist/AceList-*-linux-x86_64.tar.gz
dist/AceList-*-linux-x86_64.tar.gz.sha256
if-no-files-found: error

- name: Attest provenance
if: github.event_name == 'release' && !github.event.repository.private
uses: actions/attest-build-provenance@v2
with:
subject-path: dist/AceList-*-linux-x86_64.tar.gz

- name: Attach to the release
if: github.event_name == 'release'
env:
GH_TOKEN: ${{ github.token }}
run: |
gh release upload "${{ github.event.release.tag_name }}" \
dist/AceList-*-linux-x86_64.tar.gz \
dist/AceList-*-linux-x86_64.tar.gz.sha256 \
--clobber
18 changes: 17 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,23 @@ Todos los cambios relevantes del proyecto se registran aquí. Formato basado en
## [Sin publicar]

### Agregado
- MIT license (`LICENSE`), declared in `pyproject.toml` and shipped as `LICENSE.txt` next to `AceList.exe` in the Windows zip.
- MIT license (`LICENSE`), declared in `pyproject.toml` and shipped as `LICENSE.txt` in the
Windows and Linux packages.
- Paquete Linux x86-64 en modo carpeta con PyInstaller, tarball versionado, suma SHA-256 y smoke
test del binario contra las páginas principales y una base de datos descartable.
- Workflow de GitHub Actions que construye y prueba el paquete en Ubuntu 22.04, publica el
artefacto en cada cambio pertinente y lo adjunta a las releases con attestación de procedencia.
- `start.sh` crea el entorno virtual, instala o actualiza dependencias cuando cambia
`pyproject.toml` y usa el mismo launcher que el ejecutable.
- Autodetección del engine Linux como `acestreamengine` en `PATH` y en ubicaciones habituales bajo
`/usr` y `/opt`; al iniciarlo usa el modo `--client-console`.
- La matriz de CI ejecuta lint y tests tanto en Ubuntu como en Windows.

### Cambiado
- El ejecutable guarda sus datos según la plataforma: `%LOCALAPPDATA%\AceList` en Windows y
`$XDG_DATA_HOME/AceList` (o `~/.local/share/AceList`) en Linux.
- Los textos de errores y la documentación ya no suponen que VLC, ffmpeg y Ace Stream terminan en
`.exe`.

## [1.5.0] - 2026-10-11

Expand Down
72 changes: 53 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,48 @@ Catálogo local de enlaces Acestream. Valida el Content ID, comprueba si hay pee

## Requisitos

- Windows 10 u 11 de 64 bits.
- [Ace Stream Media](https://www.acestream.org/) instalado (su engine responde en `http://127.0.0.1:6878`). AceList puede abrirlo con el botón **Iniciar** de la barra superior.
- Linux x86-64 o Windows 10/11 de 64 bits.
- [Ace Stream](https://www.acestream.org/) instalado (su engine debe responder en `http://127.0.0.1:6878`). AceList puede abrirlo con el botón **Iniciar** de la barra superior.
- [VLC](https://www.videolan.org/vlc/) para reproducir.
- [ffmpeg](https://ffmpeg.org/download.html) para las capturas (opcional: sin ffmpeg los canales se verifican igual, sin imagen).

No hace falta instalar Python: el ejecutable lo lleva dentro.

## Instalación
## Instalación en Linux

1. En la página de [releases](https://github.com/fabiomb/AceList/releases/latest), descarga **`AceList-<versión>-win64.zip`**.
1. En la página de [releases](https://github.com/fabiomb/AceList/releases/latest), descarga **`AceList-<versión>-linux-x86_64.tar.gz`**.
2. Descomprímelo y ejecuta AceList:

```bash
tar -xzf AceList-X.Y.Z-linux-x86_64.tar.gz
cd AceList
./AceList
```

Se abre el navegador en `http://127.0.0.1:8000/`. Deja la terminal abierta mientras lo uses;
`Ctrl+C` lo detiene. Los datos se guardan en `~/.local/share/AceList` o en
`$XDG_DATA_HOME/AceList`, nunca dentro de la carpeta descomprimida.

AceList detecta `vlc`, `ffmpeg` y `acestreamengine` en `PATH`. Para el engine también revisa
`/usr/bin`, `/usr/local/bin` y `/opt/acestream`. Si tu instalación usa otra ruta o URL, indícala
en **Ajustes**. El engine también puede quedar iniciado por separado.

Opciones:

```bash
./AceList --port 8080
./AceList --no-browser
```

Para verificar la descarga:

```bash
sha256sum -c AceList-X.Y.Z-linux-x86_64.tar.gz.sha256
```

## Instalación en Windows

1. En la página de releases, descarga **`AceList-<versión>-win64.zip`**.
2. Descomprímelo donde quieras, por ejemplo en `Documentos\AceList`.
3. Haz doble clic en **`AceList.exe`**.

Expand All @@ -47,14 +79,14 @@ AceList todavía no está firmado digitalmente, así que la primera vez Windows
Para comprobar que el zip es el original, compara su huella con la del archivo `.sha256` publicado junto a él:

```powershell
Get-FileHash .\AceList-1.3.0-win64.zip -Algorithm SHA256
Get-FileHash .\AceList-1.5.0-win64.zip -Algorithm SHA256
```

### Tus datos
### Tus datos en Windows

La base de datos y las capturas se guardan en **`%LOCALAPPDATA%\AceList`** (escribe esa ruta en la barra del Explorador para abrirla), no en la carpeta del programa. Para hacer una copia de seguridad, copia esa carpeta o usa **Exportar** en el listado.

### Actualizar
### Actualizar en Windows

Cierra AceList, borra la carpeta del programa y descomprime la versión nueva en su lugar. Tus canales siguen en `%LOCALAPPDATA%\AceList` y la versión nueva actualiza la base de datos sola al arrancar.

Expand All @@ -65,7 +97,7 @@ Esa versión guarda los datos en la carpeta `data\` del código. Para llevarlos
- **Exportar e importar:** en la versión vieja, **Exportar** en el listado; en el ejecutable, sube el archivo en **Importar**. Se pasan los canales con todos sus datos, pero no el historial ni las capturas.
- **Copiar la carpeta:** con las dos versiones cerradas, copia el contenido de `data\` (`acelist.db` y `screenshots\`) a `%LOCALAPPDATA%\AceList`. Se pasa todo, incluido el historial.

### Opciones
### Opciones en Windows

```powershell
.\AceList.exe --port 8080 # usar ese puerto
Expand All @@ -74,16 +106,17 @@ Esa versión guarda los datos en la carpeta `data\` del código. Para llevarlos

### Desinstalar

Borra la carpeta del programa. Si tampoco quieres conservar tus canales, borra `%LOCALAPPDATA%\AceList`.
Borra la carpeta del programa. Si tampoco quieres conservar tus canales, borra
`~/.local/share/AceList` en Linux o `%LOCALAPPDATA%\AceList` en Windows.

## Desde el código

Si prefieres ejecutarlo desde el código fuente (necesita [Python](https://www.python.org/downloads/) 3.11 o superior):

1. Descarga o clona el repositorio.
2. Haz doble clic en **`start.bat`**.
2. En Linux ejecuta `./start.sh`; en Windows haz doble clic en **`start.bat`**.

La primera vez crea el entorno virtual e instala las dependencias (tarda un minuto). Después aplica las migraciones, arranca el servidor y abre el navegador. Los datos quedan en la carpeta `data\` del repositorio. Desde PowerShell, `.\start.ps1 -Port 8080` usa otro puerto y `.\start.ps1 -NoBrowser` no abre el navegador.
La primera vez crea el entorno virtual e instala las dependencias (tarda un minuto). Después aplica las migraciones, arranca el servidor y abre el navegador. Los datos quedan en la carpeta `data/` del repositorio. En Linux, `./start.sh --port 8080 --no-browser` pasa las opciones al launcher; en PowerShell se usan `-Port 8080` y `-NoBrowser`.

## Uso

Expand Down Expand Up @@ -113,12 +146,12 @@ Los valores de *Ajustes* se guardan en la base de datos y tienen prioridad. Las

| Variable | Por defecto | Uso |
|----------|-------------|-----|
| `ACELIST_DATA_DIR` | `%LOCALAPPDATA%\AceList` (ejecutable) o `data` (código) | Carpeta de la base de datos (`acelist.db`) y las capturas (`screenshots/`). |
| `ACELIST_PORT` | `8000` | Puerto local con `start.bat`; el ejecutable usa `--port`. |
| `ACELIST_DATA_DIR` | datos de usuario (ejecutable) o `data` (código) | Carpeta de la base de datos (`acelist.db`) y las capturas (`screenshots/`). En Linux respeta `XDG_DATA_HOME`; en Windows usa `LOCALAPPDATA`. |
| `ACELIST_PORT` | `8000` | Puerto local; el ejecutable y `start.sh` aceptan `--port`. |
| `ACELIST_ENGINE_URL` | `http://127.0.0.1:6878` | URL del engine de Ace Stream. |
| `ACELIST_ENGINE_TIMEOUT` | `15` | Segundos de espera de cada petición al engine. |
| `ACELIST_VLC_PATH` | autodetección | Ruta de `vlc.exe`. |
| `ACELIST_FFMPEG_PATH` | `PATH` | Ruta de `ffmpeg.exe`. |
| `ACELIST_VLC_PATH` | autodetección | Ruta del ejecutable de VLC. |
| `ACELIST_FFMPEG_PATH` | `PATH` | Ruta del ejecutable de ffmpeg. |
| `ACELIST_SCREENSHOT_TIMEOUT` | `30` | Segundos máximos para sacar una captura. |
| `ACELIST_CHECK_CONCURRENCY` | `2` | Verificaciones simultáneas en segundo plano. |

Expand All @@ -138,10 +171,10 @@ No hay usuarios ni contraseñas: no lo expongas a la red.

| Síntoma | Qué revisar |
|---------|-------------|
| "Ace Stream apagado" en la barra superior | Pulsa **Iniciar**, o abre Ace Stream a mano. Si no hay botón, indica la ruta de `ace_engine.exe` en *Ajustes*. |
| "Ace Stream apagado" en la barra superior | Pulsa **Iniciar**, o abre Ace Stream a mano. Si no hay botón, indica la ruta de su ejecutable en *Ajustes*. |
| El indicador está en verde pero todo sale en "Error" | En *Ajustes*, revisa la URL del engine con **Probar conexión**. |
| "No se encontró VLC" | Instala VLC o indica la ruta de `vlc.exe` en *Ajustes*. |
| Canales activos sin captura | ffmpeg no está instalado o no se encuentra: **Autodetectar rutas** en *Ajustes* o indica la ruta de `ffmpeg.exe`. |
| "No se encontró VLC" | Instala VLC o indica la ruta de su ejecutable en *Ajustes*. |
| Canales activos sin captura | ffmpeg no está instalado o no se encuentra: **Autodetectar rutas** en *Ajustes* o indica su ruta. |
| "Windows protegió su PC" al abrir `AceList.exe` | Es SmartScreen con un programa sin firma: **Más información → Ejecutar de todos modos** (ver [Aviso de Windows la primera vez](#aviso-de-windows-la-primera-vez)). |
| El antivirus bloquea `AceList.exe` | Algunos antivirus desconfían de los programas hechos con PyInstaller (falso positivo). Comprueba el SHA-256 del zip y añade una excepción para la carpeta de AceList. |
| La consola se cierra con un mensaje de error | Léelo antes de pulsar Enter: suele ser que no hay puertos libres o que la carpeta de datos no se puede escribir. |
Expand All @@ -162,7 +195,7 @@ python -m venv .venv

Los tests no necesitan el engine ni ffmpeg: el engine se simula con `respx` y nunca se contacta uno real.

Para compilar el ejecutable: `pip install -e ".[build]"` y `python windows\build.py` (ver [docs/packaging.md](docs/packaging.md)). Al publicar una release en GitHub, el CI lo compila, lo prueba y adjunta el zip.
Para compilar los ejecutables: `pip install -e ".[build]"` y `python linux/build.py` en Linux o `python windows/build.py` en Windows. Ver [empaquetado para Linux](docs/packaging-linux.md) y [para Windows](docs/packaging.md). Al publicar una release, el CI compila y prueba ambos artefactos.

Stack: Python, FastAPI, SQLite + SQLAlchemy (Alembic), Jinja2 + HTMX, httpx, ffmpeg. Detalle y justificación en [plan.md](plan.md).

Expand All @@ -185,6 +218,7 @@ El seguimiento se hace con [issues de GitHub](https://github.com/fabiomb/AceList
- [idea.md](idea.md): idea original.
- [plan.md](plan.md): alcance, arquitectura, modelo de datos y fases.
- [docs/engine-api.md](docs/engine-api.md): API del engine de Acestream observada en la práctica.
- [docs/packaging-linux.md](docs/packaging-linux.md): cómo se empaqueta el ejecutable para Linux.
- [docs/packaging.md](docs/packaging.md): cómo se empaqueta el ejecutable para Windows.
- [CHANGELOG.md](CHANGELOG.md): registro de cambios.

Expand Down
49 changes: 38 additions & 11 deletions app/acestream/install.py
Original file line number Diff line number Diff line change
@@ -1,11 +1,20 @@
import os
import shutil
import subprocess
import sys
from collections.abc import Callable, Iterable
from pathlib import Path


def engine_candidates() -> list[Path]:
"""Where Ace Stream Media puts its engine on Windows (per user, or for everyone)."""
def engine_candidates(platform: str = sys.platform) -> list[Path]:
"""Usual Ace Stream engine locations for the current operating system."""
if platform != "win32":
return [
Path("/usr/bin/acestreamengine"),
Path("/usr/local/bin/acestreamengine"),
Path("/opt/acestream/start-engine"),
Path("/opt/acestream/acestreamengine"),
]
found = []
for name in ("APPDATA", "LOCALAPPDATA"):
if root := os.environ.get(name):
Expand All @@ -16,11 +25,15 @@ def engine_candidates() -> list[Path]:
return found


def find_engine_executable(candidates: Iterable[Path] | None = None) -> str | None:
def find_engine_executable(
candidates: Iterable[Path] | None = None, *, platform: str = sys.platform
) -> str | None:
"""Path of the installed engine executable, if Ace Stream is installed."""
for candidate in engine_candidates() if candidates is None else candidates:
for candidate in engine_candidates(platform) if candidates is None else candidates:
if candidate.is_file():
return str(candidate)
if candidates is None and platform != "win32":
return shutil.which("acestreamengine") or shutil.which("start-engine")
return None


Expand All @@ -29,22 +42,36 @@ class EngineStartError(Exception):


def start_engine(
path: str, *, launcher: Callable[..., subprocess.Popen] = subprocess.Popen
path: str,
*,
launcher: Callable[..., subprocess.Popen] = subprocess.Popen,
platform: str = sys.platform,
) -> None:
"""Launches the installed engine and returns at once; it takes a few seconds to answer."""
executable = Path(path)
if not executable.is_file():
raise EngineStartError(f"engine executable not found: {path}")
try:
# An argument list and no shell; detached so it outlives AceList, like VLC.
# The official Linux engine needs an explicit client mode. Windows' GUI
# executable selects it itself.
command = [str(executable)]
if platform != "win32":
command.append("--client-console")
options = {
"stdin": subprocess.DEVNULL,
"stdout": subprocess.DEVNULL,
"stderr": subprocess.DEVNULL,
"close_fds": True,
}
if platform == "win32":
options["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0)
else:
options["start_new_session"] = True
launcher(
[str(executable)],
command,
cwd=str(executable.parent),
stdin=subprocess.DEVNULL,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
close_fds=True,
creationflags=getattr(subprocess, "DETACHED_PROCESS", 0),
**options,
)
except OSError as exc:
raise EngineStartError(f"could not start the engine: {exc}") from exc
21 changes: 16 additions & 5 deletions app/config.py
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
import os
import sys
from collections.abc import Mapping
from pathlib import Path
from pathlib import Path, PurePosixPath

ROOT_DIR = Path(__file__).resolve().parent.parent

# True inside the Windows executable built with PyInstaller (see docs/packaging.md).
# True inside an executable built with PyInstaller (see docs/packaging.md).
FROZEN = bool(getattr(sys, "frozen", False))


Expand All @@ -17,16 +17,27 @@ def resource_dir(frozen: bool = FROZEN) -> Path:
return Path(getattr(sys, "_MEIPASS", ROOT_DIR)) if frozen else ROOT_DIR


def default_data_dir(frozen: bool = FROZEN, environ: Mapping[str, str] = os.environ) -> Path:
def default_data_dir(
frozen: bool = FROZEN,
environ: Mapping[str, str] = os.environ,
platform: str = sys.platform,
) -> Path:
"""Where the database and screenshots go unless `ACELIST_DATA_DIR` says otherwise.

The executable keeps them in the user's profile, so replacing the program folder on
an update, or unpacking it somewhere read-only, never touches them.
"""
if not frozen:
return ROOT_DIR / "data"
local = environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
return Path(local) / "AceList"
if platform == "win32":
local = environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
return Path(local) / "AceList"
# Follow the XDG base-directory convention used by Linux desktops. An absolute
# XDG_DATA_HOME is required by the specification; ignore a malformed relative one.
xdg_value = environ.get("XDG_DATA_HOME")
xdg = Path(xdg_value) if xdg_value and PurePosixPath(xdg_value).is_absolute() else None
base = xdg if xdg else Path.home() / ".local" / "share"
return base / "AceList"


RESOURCE_DIR = resource_dir()
Expand Down
Loading