@hed-hog/studio

1. Visão geral do módulo

O módulo @hed-hog/studio é responsável pela gestão integrada de projetos de produção audiovisual, incluindo o controle de projetos, cenas, sessões de gravação, tomadas, ativos de mídia, perfis de armazenamento, incidentes, edição e publicação. Ele oferece uma API REST para consulta e manipulação dos dados relacionados ao fluxo de produção, com foco em ambientes de estúdio.

2. Escopo e responsabilidades

• Gerenciamento de projetos audiovisuais e seus estágios.
• Controle de cenas, sessões de gravação e tomadas.
• Administração de ativos de mídia e perfis de armazenamento.
• Registro e acompanhamento de incidentes durante a produção.
• Suporte à edição e publicação dos conteúdos produzidos.
• Fornecimento de esquemas de formulários para criação e edição de entidades.
• Controle de acesso baseado em papéis (roles).

3. Endpoints

Todos os endpoints requerem autenticação e autorização via roles admin ou admin-studio.

| Método | Path | Autenticação | Descrição | |--------|---------------------------|--------------|--------------------------------------------| | GET | /studio/data | Sim | Retorna dados gerais e totais do estúdio. | | GET | /studio/projects | Sim | Lista projetos existentes. | | GET | /studio/projects/:id | Sim | Obtém detalhes de um projeto pelo ID. | | GET | /studio/projects/form | Sim | Retorna esquema do formulário de projeto. | | GET | /studio/scenes | Sim | Lista cenas cadastradas. | | GET | /studio/scenes/form | Sim | Retorna esquema do formulário de cena. | | GET | /studio/sessions | Sim | Lista sessões de gravação. | | GET | /studio/sessions/:id | Sim | Obtém detalhes de uma sessão pelo ID. | | GET | /studio/sessions/form | Sim | Retorna esquema do formulário de sessão. | | GET | /studio/takes | Sim | Lista tomadas (takes). | | GET | /studio/takes/:id | Sim | Obtém detalhes de uma tomada pelo ID. | | GET | /studio/assets | Sim | Lista ativos de mídia. | | GET | /studio/storage-profiles | Sim | Lista perfis de armazenamento. | | GET | /studio/storage-profiles/form | Sim | Retorna esquema do formulário de perfil de armazenamento. | | GET | /studio/incidents | Sim | Lista incidentes registrados. | | GET | /studio/editing | Sim | Retorna dados relacionados à edição. | | GET | /studio/publication | Sim | Retorna dados relacionados à publicação. |

Detalhes dos endpoints

GET /studio/data

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna totais e status gerais do estúdio.
• Resposta:

{
  "totals": {
    "projects": 24,
    "inRecording": 4,
    "inEditing": 7,
    "pendingIngestion": 13,
    "uploadFailures": 2,
    "readyToPublish": 3
  },
  "updatedAt": "ISO8601 timestamp"
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/projects

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista projetos com informações resumidas.
• Resposta:

{
  "data": [
    {
      "id": 1,
      "title": "Curso de Node Avancado - Aula 12",
      "projectType": "course_lesson",
      "status": "in_recording",
      "currentStage": "recording",
      "ownerUserId": 1,
      "updatedAt": "ISO8601 timestamp"
    }
  ],
  "total": 1
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/projects/:id

• Autenticação: Sim (roles: admin, admin-studio)
• Parâmetros:
  • id (integer): ID do projeto
• Descrição: Obtém detalhes do projeto especificado.
• Resposta:

{
  "id": 1,
  "title": "Projeto Studio",
  "status": "planned",
  "currentStage": "preparation"
}

• Erros comuns: 401 Unauthorized, 403 Forbidden, 404 Not Found

GET /studio/projects/form

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna esquema dos campos para formulário de projeto.
• Resposta:

{
  "fields": ["title", "description", "projectType", "status"]
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/scenes

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista cenas (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/scenes/form

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna esquema dos campos para formulário de cena.
• Resposta:

{
  "fields": ["name", "description", "sequenceOrder", "status"]
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/sessions

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista sessões de gravação (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/sessions/:id

• Autenticação: Sim (roles: admin, admin-studio)
• Parâmetros:
  • id (integer): ID da sessão
• Descrição: Obtém detalhes da sessão especificada.
• Resposta:

{
  "id": 1,
  "status": "idle"
}

• Erros comuns: 401 Unauthorized, 403 Forbidden, 404 Not Found

GET /studio/sessions/form

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna esquema dos campos para formulário de sessão.
• Resposta:

{
  "fields": ["title", "sessionType", "status", "roomKey"]
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/takes

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista tomadas (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/takes/:id

• Autenticação: Sim (roles: admin, admin-studio)
• Parâmetros:
  • id (integer): ID da tomada
• Descrição: Obtém detalhes da tomada especificada.
• Resposta:

{
  "id": 1,
  "status": "pending"
}

• Erros comuns: 401 Unauthorized, 403 Forbidden, 404 Not Found

GET /studio/assets

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista ativos de mídia (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/storage-profiles

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista perfis de armazenamento (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/storage-profiles/form

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna esquema dos campos para formulário de perfil de armazenamento.
• Resposta:

{
  "fields": ["name", "providerType", "bucketName", "region", "basePath"]
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/incidents

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Lista incidentes registrados (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/editing

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna dados relacionados à edição (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

GET /studio/publication

• Autenticação: Sim (roles: admin, admin-studio)
• Descrição: Retorna dados relacionados à publicação (retorna array vazio no momento).
• Resposta:

{
  "data": []
}

• Erros comuns: 401 Unauthorized, 403 Forbidden

4. Regras de autenticação e autorização

• Todos os endpoints são protegidos e requerem autenticação.
• O acesso é restrito a usuários com os papéis (roles) admin ou admin-studio.
• O papel admin-studio é definido como "Administrador de Studio" com acesso total à gestão do estúdio.

5. Estruturas de request/response

Exemplos de estruturas de resposta

• Projeto (Project):

{
  "id": 1,
  "title": "Projeto Studio",
  "status": "planned",
  "currentStage": "preparation"
}

• Projeto na listagem:

{
  "id": 1,
  "title": "Curso de Node Avancado - Aula 12",
  "projectType": "course_lesson",
  "status": "in_recording",
  "currentStage": "recording",
  "ownerUserId": 1,
  "updatedAt": "ISO8601 timestamp"
}

• Formulários (exemplo para projeto):

{
  "fields": ["title", "description", "projectType", "status"]
}

• Dados gerais do estúdio:

{
  "totals": {
    "projects": 24,
    "inRecording": 4,
    "inEditing": 7,
    "pendingIngestion": 13,
    "uploadFailures": 2,
    "readyToPublish": 3
  },
  "updatedAt": "ISO8601 timestamp"
}

6. Erros comuns

• 401 Unauthorized: Usuário não autenticado.
• 403 Forbidden: Usuário autenticado, mas sem permissão para acessar o recurso.
• 404 Not Found: Recurso solicitado não encontrado (ex: projeto, sessão ou tomada inexistente).
• 400 Bad Request: Parâmetros inválidos (ex: ID não numérico).

7. Banco de dados (tabelas YAML)

A seguir, tabelas principais relacionadas ao módulo studio com suas finalidades e detalhes.

production_project

• Finalidade: Armazena projetos de produção audiovisual.
• Colunas principais:
  • id (PK)
  • uuid (varchar(36), nullable)
  • title (string)
  • slug (slug, único)
  • description (text, nullable)
  • project_type (enum: course_lesson, standalone, social_content, campaign_asset, other; default: standalone)
  • status (enum: draft, planned, in_recording, recorded, in_editing, in_finalization, ready_to_publish, published, archived, cancelled; default: draft)
  • current_stage (enum: preparation, recording, rough_cut, cleanup, finalization, publication; default: preparation)
  • cover_file_id, thumbnail_file_id (FK para file, nullable)
  • owner_user_id, assigned_editor_user_id (FK para user, nullable)
  • Datas importantes: planned_at, recorded_at, published_at, started_at, finished_at (datetime, nullable)
  • metadata_json (json, nullable)
  • Controle de criação/atualização e exclusão lógica (deleted_at nullable)
• Índices: slug (único), status, project_type+status, current_stage, owner_user_id, assigned_editor_user_id, deleted_at

scene

• Finalidade: Representa cenas dentro de um projeto.
• Colunas principais:
  • id (PK)
  • production_project_id (FK para production_project)
  • name (string)
  • slug (slug)
  • description, script_excerpt, notes (text, nullable)
  • sequence_order (int, default 1)
  • estimated_duration_seconds (int, nullable)
  • expected_output_type (enum: talking_head, screen_demo, interview, presentation, outro, intro, other; default: talking_head)
  • status (enum: pending, ready_to_record, recording, recorded, approved_for_edit, edited, archived; default: pending)
  • Controle de criação/atualização e exclusão lógica (deleted_at nullable)
• Índices: production_project_id+sequence_order, production_project_id+status, slug, deleted_at

recording_session

• Finalidade: Sessões de gravação vinculadas a projetos e cenas.
• Colunas principais:
  • id (PK)
  • production_project_id (FK para production_project)
  • active_scene_id (FK para scene, nullable)
  • title (string)
  • description (text, nullable)
  • session_type (enum: local, remote_collaborative, hybrid; default: local)
  • status (enum: idle, arming, ready, start_requested, recording, stop_requested, processing, finished, cancelled; default: idle)
  • room_key, server_clock_reference (varchar, nullable)
  • sync_mode (enum: server_authoritative, host_assisted, local_only; default: server_authoritative)
  • host_user_id (FK para user, nullable)
  • Datas: started_at, ended_at (nullable)
  • Controle de criação/atualização e exclusão lógica (deleted_at nullable)
• Índices: production_project_id+status, room_key, host_user_id, active_scene_id, deleted_at

scene_take

• Finalidade: Tomadas (takes) de cenas em sessões de gravação.
• Colunas principais:
  • id (PK)
  • production_project_id (FK para production_project)
  • scene_id (FK para scene)
  • recording_session_id (FK para recording_session)
  • take_number (int)
  • take_label (varchar(120), nullable)
  • status (enum: pending, armed, recording, stopped, uploaded, validated, partial, approved, discarded, selected; default: pending)
  • is_selected (boolean, default false)
  • sync_timecode_base (varchar(120), nullable)
  • Datas: started_at, ended_at (nullable)
  • duration_ms (int, nullable)
  • notes, metadata_json (text/json, nullable)
  • Controle de criação/atualização e exclusão lógica (deleted_at nullable)
• Índices: scene_id+take_number (único), recording_session_id+status, is_selected, deleted_at

storage_profile

• Finalidade: Perfis de armazenamento para ingestão e arquivos.
• Colunas principais:
  • id (PK)
  • name (string, único)
  • provider_type (enum: s3, minio, r2, compatible_s3; default: compatible_s3)
  • bucket_name (string)
  • region, endpoint_url, base_path, path_template (varchar, nullable)
  • access_key_encrypted, secret_key_encrypted (text, nullable)
  • Flags: force_path_style (boolean, default false), is_default (boolean, default false), is_active (boolean, default true)
  • test_status (enum: unknown, success, failed; default: unknown)
  • last_tested_at (datetime, nullable)
  • Controle de criação/atualização e exclusão lógica (deleted_at nullable)
• Índices: name (único), provider_type, is_default, is_active, deleted_at

recording_incident

• Finalidade: Registro de incidentes durante sessões de gravação.
• Colunas principais:
  • id (PK)
  • recording_session_id (FK para recording_session, nullable)
  • scene_take_id (FK para scene_take, nullable)
  • participant_recording_id (FK para participant_recording, nullable)
  • session_participant_id (FK para session_participant, nullable)
  • incident_type (enum: no_audio, no_video, no_screen, corrupted_file, upload_failed, participant_disconnected, delayed_start, delayed_stop, partial_take, sync_issue, other; default: other)
  • severity (enum: low, medium, high, critical; default: medium)
  • description (text)
  • Datas: detected_at, resolved_at (nullable)
  • resolution_notes (text, nullable)
  • metadata_json (json, nullable)
  • Controle de criação/atualização
• Índices: recording_session_id, scene_take_id, participant_recording_id, severity, incident_type, resolved_at

Outras tabelas importantes

• capture_agent: agentes de captura vinculados a participantes.
• edit_composition, edit_pipeline, edit_stage_execution: controle do pipeline e composições de edição.
• editor_delivery_package: pacotes de entrega para editores.
• ingestion_job: trabalhos de ingestão de arquivos.
• media_asset: ativos de mídia vinculados a projetos, cenas e tomadas.
• participant_command_ack, participant_recording: controle de gravações e comandos de participantes.
• production_binding: ligações e relacionamentos de projetos.
• publication_target: destinos de publicação dos projetos.
• recorded_file: arquivos gravados vinculados a ingestões.
• recording_command: comandos emitidos para sessões de gravação.
• recording_session: sessões de gravação.
• scene_take: tomadas de cenas.
• session_participant: participantes em sessões.
• sync_marker: marcadores de sincronização.

8. Regras de negócio relevantes

• O fluxo de produção é dividido em estágios (current_stage), como preparação, gravação, edição, finalização e publicação.
• Projetos possuem status que refletem seu progresso, desde rascunho até publicado ou cancelado.
• Tomadas (scene_take) possuem status detalhados para controle do processo de gravação e aprovação.
• Perfis de armazenamento são configurados para suportar diferentes provedores e são testados para garantir disponibilidade.
• Incidentes são categorizados por tipo e severidade, permitindo acompanhamento e resolução.
• O acesso à API é restrito a administradores com papéis específicos para garantir segurança e controle.
• Formulários dinâmicos são fornecidos para facilitar a criação e edição de entidades no sistema.

9. Guia rápido de uso (exemplos)

Obter dados gerais do estúdio

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/studio/data

Listar projetos

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/studio/projects

Obter detalhes de um projeto

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/studio/projects/1

Obter esquema do formulário de projeto

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/studio/projects/form

Listar sessões de gravação

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/studio/sessions

Obter detalhes de uma sessão

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/studio/sessions/1

Nota: Substitua <token> pelo token JWT válido com as permissões adequadas.

Este módulo é parte integrante do monorepo HedHog e depende dos módulos @hed-hog/api-locale, @hed-hog/api-pagination, @hed-hog/api-prisma e @nestjs/config para seu funcionamento.