🎙️

Seed de Podcasts

← Voltar ao Índice

Seed de Podcasts Portugueses

Visão Geral

Este documento descreve os sistemas de seed para popular a base de dados com podcasts portugueses.

Existem dois scripts disponíveis:

Script 1: Seed Rápido (Exemplos)

Descrição

O script seed-podcasts.ts cria 3 podcasts de demonstração com episódios de exemplo para testes rápidos.

Como Executar

# Via npm script
npm run seed:podcasts

# Ou via ts-node
npx ts-node apps/api/src/scripts/seed-podcasts.ts

Podcasts de Exemplo

  1. Tech Talk Portugal - Tecnologia e programação (3 episódios)
  2. História de Portugal - História e cultura (1 episódio)
  3. Futebol em Debate - Desporto (sem episódios)

Uso: Ideal para desenvolvimento e testes rápidos.

Script 2: Seed Completo (Podcast Index API)

Descrição

O script seed-podcasts-full.ts recolhe o máximo de podcasts portugueses disponíveis via Podcast Index API.

Funcionalidades

Credenciais Necessárias

⚠️ IMPORTANTE: Este script requer credenciais do Podcast Index API no ficheiro .env:

PODCAST_INDEX_API_KEY=your_api_key_here
PODCAST_INDEX_API_SECRET=your_api_secret_here

Para obter as credenciais:

  1. Aceder a https://api.podcastindex.org/
  2. Criar conta gratuita
  3. Gerar API Key e Secret
  4. Adicionar ao .env

Como Executar

# Via npm script (recomendado)
npm run seed:podcasts:full

# Ou via ts-node
npx ts-node apps/api/src/scripts/seed-podcasts-full.ts

Fontes de Dados

O script recolhe de duas fontes simultâneas:

  1. Trending Podcasts (/podcasts/trending)

    • Podcasts populares em português
    • Limite: 1000 podcasts
    • Ordenação: Por popularidade

  2. Recent Feeds (/recent/feeds)

    • Podcasts recentemente atualizados
    • Limite: 1000 podcasts
    • Ordenação: Por data de atualização

Volume Esperado

Metadados Incluídos

interface PodcastData {
  title: string;              // Título do podcast
  description: string;        // Descrição completa
  rss_url: string;           // URL do feed RSS
  author: string;            // Autor/criador
  logo: string;              // URL da imagem/artwork
  language: string;          // Idioma (pt)
  categories: string[];      // Categorias do iTunes
  external_id: string;       // ID único do Podcast Index
  itunes_id: number;         // ID do iTunes (se disponível)
  homepage: string;          // Website oficial
  explicit: boolean;         // Conteúdo explícito
  episode_count: number;     // Número de episódios
}

Autenticação SHA1

O script implementa a autenticação requerida pela API:

const hash = crypto
  .createHash('sha1')
  .update(apiKey + apiSecret + timestamp)
  .digest('hex');

headers: {
  'X-Auth-Key': apiKey,
  'X-Auth-Date': timestamp,
  'Authorization': hash,
}

Output do Script

🌱 A iniciar seed COMPLETO de podcasts portugueses...
⚠️  Este processo pode demorar vários minutos!

🌐 A recolher podcasts trending (pt)...
   ✅ 1000 podcasts trending encontrados

🌐 A recolher podcasts recentes (pt)...
   ✅ 873 podcasts recentes encontrados

✅ 1456 podcasts únicos e funcionais encontrados
📊 A processar podcasts...

✅ [1/1456] Tech Talks PT - João Silva (45 episódios)
✅ [2/1456] História Viva - Maria Costa (128 episódios)
⏭️  [3/1456] Futebol Total - já existe
✅ [4/1456] Conversas de Café - Pedro Santos (67 episódios)
...

📊 Sumário Final:
   ✅ Criados com sucesso: 987
   ⏭️  Já existentes (ignorados): 456
   ❌ Erros: 13
   🎙️  Total processados: 1456

🗄️  Total de podcasts na base de dados: 1210

✨ Seed completo de podcasts concluído!

Comparação dos Scripts

Característica seed-podcasts.ts seed-podcasts-full.ts
Volume 3 podcasts 500-1500 podcasts
Fonte Dados de exemplo Podcast Index API
Tempo ~2 segundos 5-15 minutos
Credenciais Não requer Requer API Key/Secret
Episódios Criados manualmente Apenas metadata inicial
Uso Desenvolvimento/testes Base de produção

Pré-requisitos

Ambos os Scripts

  1. MongoDB deve estar em execução
  2. Variáveis de ambiente configuradas (.env)
  3. Dependências instaladas (npm install)

Apenas seed-podcasts-full.ts

  1. Credenciais da API no .env:
    PODCAST_INDEX_API_KEY=your_key
PODCAST_INDEX_API_SECRET=your_secret

Sincronização de Episódios

⚠️ NOTA IMPORTANTE: Os scripts de seed apenas criam os registos de podcasts.

Para recolher os episódios de cada podcast, executar posteriormente:

# Worker automático (sincronização diária)
npx nx serve worker

# Ou trigger manual via API
curl -X POST http://localhost:3001/api/jobs/sync-episodes

Ver documentação completa em:

Filtros de Qualidade

seed-podcasts-full.ts aplica os seguintes filtros:

✅ Incluir apenas:

❌ Excluir:

Troubleshooting

Erro: "PODCAST_INDEX_API_KEY não definida"

Solução: Adicionar credenciais ao .env:

PODCAST_INDEX_API_KEY=your_key_here
PODCAST_INDEX_API_SECRET=your_secret_here

Erro: "Cannot GET /api/1.0/podcasts/trending"

Causa: Credenciais inválidas ou expiradas

Solução:

  1. Verificar credenciais no .env
  2. Testar autenticação: npm run test:podcast-api-auth
  3. Regenerar credenciais se necessário

Script muito lento

Causa: Grande volume de podcasts a processar

Soluções:

Muitos erros durante o seed

Causa: Problemas de rede ou API rate limiting

Solução:

Estrutura de Ficheiros

apps/api/src/scripts/
├── seed-podcasts.ts          # Seed rápido (exemplos)
└── seed-podcasts-full.ts     # Seed completo (API)

package.json                  # Scripts npm
├── seed:podcasts            → seed-podcasts.ts
└── seed:podcasts:full       → seed-podcasts-full.ts

Próximos Passos

Após executar o seed:

  1. ✅ Verificar podcasts criados: GET /api/podcasts
  2. 🔄 Sincronizar episódios: Worker automático ou trigger manual
  3. 📊 Monitorizar sincronização: GET http://localhost:3001/api/jobs/stats
  4. 🎵 Testar playback: Cliente frontend

Referências