Aecsa Ubuntu Screen Recorder

Grabador de pantalla para Ubuntu para Aecsa.

Funcionalidades

• Identificación mediante usuario del sistema actual y detección del usuario administrador.
• Soporte opcional de autenticación remota via API.
• Grabación de pantalla por segmentos independientes.
• Audio opcional usando PulseAudio/PipeWire si pactl esta disponible.
• Cola persistente de videos pendientes en JSON.
• Reintento de subida a API compatible con el flujo:
• POST /recordings
• POST /recordings/complete
• Panel de configuracion del dispositivo.
• Gestor de videos locales.

Requisitos y dependencias

Consulta DEPENDENCIAS_UBUNTU.md para instrucciones detalladas de instalación, validación y resolución de problemas en Ubuntu.

Instalación

La aplicación debe instalarse una sola vez desde un usuario administrador. El instalador copia el aplicativo a /opt/aecsa-ubuntu-recorder y crea un servicio global en /etc/systemd/system/aecsa-recorder.service.

Opción recomendada para varias máquinas: paquete .deb

Para llevar la aplicación a otros equipos Ubuntu, genera un paquete instalable:

# Desarrollo/local: empaqueta http://127.0.0.1:3650
./build-deb.sh --arch amd64 --profile development 1.0

# Release/produccion: empaqueta https://grbwin.aecsa.com.co:8005
./build-deb.sh --arch amd64 --profile release 1.0

El perfil release deja AECSA_VIDEO_API_ENDPOINT=https://grbwin.aecsa.com.co:8005 dentro del .env empaquetado. Si necesitas un endpoint puntual, usa --api-endpoint URL.

El archivo queda en dist/, por ejemplo:

dist/aecsa-ubuntu-recorder_1.0_amd64.deb

En cada máquina destino puedes abrir ese .deb con doble clic o instalarlo por terminal:

./install-aecsa-ubuntu-recorder_1.0_amd64.sh

Ese instalador revisa la version instalada: si es la misma no realiza cambios, si es mayor bloquea el downgrade, y si es menor instala la actualizacion. El paquete instala dependencias mediante apt, copia la app a /opt/aecsa-ubuntu-recorder y habilita el servicio global aecsa-recorder.service.

Nota: el .deb declara las dependencias para que apt las instale automaticamente desde los repositorios configurados de Ubuntu. Si el equipo destino no tiene internet ni repositorios locales, primero hay que preparar un instalador offline con esas dependencias.

Para un instalador con dependencias incluidas, genera un bundle offline desde una maquina Ubuntu con internet:

./build-offline-bundle.sh --arch amd64 --profile release 1.0

Eso crea dos salidas:

dist/aecsa-ubuntu-recorder_1.0_amd64_offline.run
dist/aecsa-ubuntu-recorder_1.0_amd64_offline.tar.gz

Para distribuir a usuarios finales usa el .run: es un unico archivo todo-en-uno con el wizard, el .deb y las dependencias. En la maquina destino se ejecuta con doble clic o por consola:

./aecsa-ubuntu-recorder_1.0_amd64_offline.run

El .tar.gz queda como alternativa para soporte tecnico.

El instalador offline aplica la misma regla de versiones: no toca una instalacion con la misma version y actualiza cuando el paquete tiene una version mayor.

Para equipos ARM de 64 bits, genera otro bundle:

./build-offline-bundle.sh --arch arm64 1.0

Si generas una arquitectura distinta a la de tu maquina, primero habilitala en apt:

sudo dpkg --add-architecture arm64
sudo apt update

Cada generación deja trazabilidad en:

dist/build-history.log
dist/aecsa-ubuntu-recorder_1.0_amd64_BUILD_INFO.txt

Los bundles offline tambien incluyen un BUILD_INFO.txt dentro de la carpeta generada.

Instalación desde el código fuente

./install-system-wide.sh

El instalador valida dependencias requeridas (python3, python3-tk, ffmpeg). Si falta alguna, instala primero:

sudo apt update
sudo apt install -y python3 python3-tk ffmpeg pulseaudio-utils

Después de esa instalación, el grabador queda habilitado a nivel de sistema. El servicio detecta la sesión gráfica activa con loginctl y arranca el grabador como el usuario dueño de esa sesión, incluyendo usuarios administradores. No se requiere instalarlo usuario por usuario.

El servicio global ejecuta run-recording.sh --autostart dentro del entorno gráfico del usuario activo. La instalación aplica para todos los usuarios por defecto.

Aunque la instalación es global, cada usuario conserva sus propios datos locales en:

~/.local/share/aecsa-ubuntu-recorder

De esta forma, cada usuario del dispositivo tiene sus propios registros y videos, y no hay mezcla de datos entre cuentas.

No ejecutes el grabador con sudo para grabar la sesión de un usuario: el servicio global lo inicia dentro de la sesión gráfica correcta.

Desinstalación

Para quitar la instalación global y el servicio:

cd ubuntu-screen-recorder
./uninstall-system-wide.sh

El desinstalador detiene procesos activos que estén corriendo desde /opt/aecsa-ubuntu-recorder, deshabilita y elimina /etc/systemd/system/aecsa-recorder.service, limpia el autostart legacy si existía y borra /opt/aecsa-ubuntu-recorder.

Por defecto conserva los datos locales del usuario en:

~/.local/share/aecsa-ubuntu-recorder

Si también necesitas eliminar los datos locales del usuario que ejecuta la desinstalación:

./uninstall-system-wide.sh --purge-current-user-data

Configuración

Los defaults globales viven en .env y se copian junto con la app a /opt/aecsa-ubuntu-recorder/.env. La app no crea un config.json editable por cada usuario para controlar el arranque; por defecto todos heredan la configuración global.

Para individualizar la configuración de un usuario, un administrador debe crear un archivo en:

/etc/aecsa-ubuntu-recorder/config.<usuario>.json

Por ejemplo:

sudo cp /etc/aecsa-ubuntu-recorder/config.json.example /etc/aecsa-ubuntu-recorder/config.cristian.gaitan564.json
sudo nano /etc/aecsa-ubuntu-recorder/config.cristian.gaitan564.json
sudo systemctl restart aecsa-recorder.service

Si ese archivo no existe, el usuario hereda los defaults globales y start_on_boot=true.

Orden de prioridad para campos de AppConfig:

1. /etc/aecsa-ubuntu-recorder/config.<usuario>.json, si existe.
2. Variables de entorno del proceso.
3. /etc/aecsa-ubuntu-recorder.env, si existe.
4. .env de la instalación.

Para rutas como AECSA_APP_DIR y AECSA_CONFIG_DIR, que se resuelven antes de leer overrides JSON, aplica la prioridad: variable de entorno, /etc/aecsa-ubuntu-recorder.env, .env.

Los parámetros principales son AECSA_START_ON_BOOT, AECSA_DEBUG_MODE, AECSA_SEGMENT_SECONDS, AECSA_OUTPUT_FORMAT, AECSA_VIDEO_API_ENDPOINT, AECSA_RECORDING_FRAMERATE, AECSA_VIDEO_BITRATE, AECSA_AUDIO_BITRATE y AECSA_UPLOAD_TIMEOUT_SECONDS.

Ejecutar Manualmente

La aplicación se maneja como dos subproyectos MVC separados:

• Grabador de pantalla: python3 -m recorder
• Sincronizador de videos: python3 -m sync
• Sincronizador sin interfaz: python3 -m sync --once

También hay scripts de lanzamiento directo:

cd ubuntu-screen-recorder
./run-recording.sh
./run-sync.sh

El script ./run-recording.sh inicia el grabador en segundo plano sin mostrar UI de control de grabación, pausa o parada por defecto. Si debug_mode está activado globalmente en .env o para un usuario en /etc/aecsa-ubuntu-recorder/config.<usuario>.json, la app abre una interfaz de depuración con controles manuales.

La grabación comienza automáticamente al iniciar la aplicación y se detiene cuando el usuario cierra la ventana o el sistema envía una señal de apagado/cierre de sesión.

Si ffmpeg no está instalado, la app permite administrar configuración y videos, pero no inicia grabación.

Los datos locales se guardan en:

~/.local/share/aecsa-ubuntu-recorder

Los videos quedan en ~/.local/share/aecsa-ubuntu-recorder/recordings/ y los logs en ~/.local/share/aecsa-ubuntu-recorder/logs/.

Documentación por componente

• Grabador (detalles de comportamiento, ffmpeg, configuración): RECORDING.md
• Sincronizador / uploader (endpoints, multipart, retries): SYNC.md