@xnkee/n8n-nodes-cobalt

Community nodes do n8n para uma instância self-hosted do cobalt. Baixa vídeo, áudio, legendas e galerias de fotos de 21 serviços, direto para o campo binário do item.

O briefing original do projeto está em docs/OBJETIVO.md.

• 1 node genérico (Cobalt) com todas as opções da API.
• 21 nodes pré-configurados, um por serviço, já com placeholder de link, modo de download e só as opções que aquele serviço aceita.
• Uma credencial só (Cobalt API) compartilhada por todos — a URL da sua instância fica na credencial, nada fica embutido no pacote.
• Todos são usableAsTool, então funcionam dentro do AI Agent.

Instalação

Pela interface do n8n (self-hosted)

Settings → Community nodes → Install → nome do pacote: @xnkee/n8n-nodes-cobalt.

Manual

cd ~/.n8n
npm install @xnkee/n8n-nodes-cobalt

Reinicie o n8n depois.

Docker

Se roda em container, instale no volume do n8n ou use a variável N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true para liberar os nodes como ferramenta de AI Agent.

Subir o cobalt

Exemplo de stack em docker-compose.yml (Docker Swarm + Traefik). Troque cobalt.seudominio.com pelo seu domínio antes de subir:

docker stack deploy -c docker-compose.yml cobalt

Pontos de atenção:

• API_URL precisa ser a URL pública final, com barra no fim. É ela que o cobalt usa para montar os links de tunnel.
• O n8n precisa alcançar a instância. No mesmo swarm dá para usar http://cobalt:9000 na credencial e pular o Traefik.
• read_only: true impede escrita no container. Se for usar API_KEY_URL apontando para um arquivo, monte um volume para ele.
• Instâncias públicas do cobalt bloqueiam uso por terceiros. Este pacote é feito para a sua instância.

Credencial: Cobalt API

Toda a configuração de acesso fica aqui — nenhum endereço vem embutido nos nodes.

| Campo | Descrição | |---|---| | Instance URL | Base da sua instância, ex.: https://cobalt.seudominio.com ou http://cobalt:9000 | | Authentication | None, API Key ou Bearer Token | | Token | Enviado como Authorization: <scheme> <token> | | Ignore SSL Issues | Para certificado self-signed |

• None — instância aberta, sem API_KEY_URL nem Turnstile.
• API Key — chave estática do arquivo apontado por API_KEY_URL na instância.
• Bearer Token — JWT obtido no POST /session, para instâncias com Cloudflare Turnstile. Use o node Cobalt → recurso Session → Create para gerar o token.

O botão de testar credencial faz um GET / na instância.

Nodes

Cobalt (genérico)

| Recurso | Operação | O que faz | |---|---|---| | Media | Download File | Chama POST / e baixa o arquivo para o binário do item | | Media | Get Link | Chama POST / e devolve só o JSON (tunnel/redirect/picker) | | Instance | Get Info | GET / — versão, serviços suportados, sitekey do Turnstile | | Session | Create | POST /session — troca a solução do Turnstile por um bearer token |

Nodes por serviço

Todos têm as operações Download File e Get Link:

| Node | Serviço | Domínios | Opções extras | |---|---|---|---| | Cobalt YouTube | youtube | youtube.com, youtu.be, music.youtube.com | codec, container, dub, HLS, better audio | | Cobalt TikTok | tiktok | tiktok.com, vm/vt.tiktok.com | full audio, H265 | | Cobalt Instagram | instagram | instagram.com, ddinstagram.com | — | | Cobalt X | twitter | x.com, twitter.com, vxtwitter.com | convert GIF | | Cobalt Facebook | facebook | facebook.com, fb.watch | — | | Cobalt Reddit | reddit | reddit.com, redd.it | — | | Cobalt Twitch | twitch | twitch.tv, clips.twitch.tv | — | | Cobalt Vimeo | vimeo | vimeo.com | — | | Cobalt SoundCloud | soundcloud | soundcloud.com | só áudio | | Cobalt Pinterest | pinterest | pinterest.com, pin.it | — | | Cobalt Snapchat | snapchat | snapchat.com | — | | Cobalt Tumblr | tumblr | tumblr.com | convert GIF | | Cobalt Bluesky | bsky | bsky.app | — | | Cobalt Dailymotion | dailymotion | dailymotion.com, dai.ly | — | | Cobalt Loom | loom | loom.com | — | | Cobalt Streamable | streamable | streamable.com | — | | Cobalt Bilibili | bilibili | bilibili.com, b23.tv | — | | Cobalt VK | vk | vk.com, vkvideo.ru | — | | Cobalt OK | ok | ok.ru | — | | Cobalt Rutube | rutube | rutube.ru | — | | Cobalt Newgrounds | newgrounds | newgrounds.com | — |

Opções

Campos fixos em todos os nodes de mídia:

| Campo | Valores | |---|---| | URL | link da mídia | | Download Mode | Auto · Audio Only · Mute | | Put Output File in Field | nome do campo binário de saída, padrão data |

Dentro de Options (só aparecem as que o serviço aceita):

| Opção | Valores | Padrão | |---|---|---| | Always Proxy | boolean | false | | Audio Bitrate | 320 / 256 / 128 / 96 / 64 / 8 kbps | 128 | | Audio Format | best / mp3 / ogg / wav / opus | mp3 | | Disable Metadata | boolean | false | | Filename Style | classic / basic / pretty / nerdy | basic | | Local Processing | disabled / preferred / forced | disabled | | Subtitle Language | ISO 639-1 | — | | Video Quality | max / 4320 / 2160 / 1440 / 1080 / 720 / 480 / 360 / 240 / 144 | 1080 | | Allow H265 | boolean (TikTok) | false | | Convert GIF | boolean (X, Tumblr) | true | | TikTok Full Audio | boolean | false | | YouTube Better Audio | boolean | false | | YouTube Dub Language | ISO 639-1 | — | | YouTube HLS | boolean | false | | YouTube Video Codec | h264 / av1 / vp9 | h264 | | YouTube Video Container | auto / mp4 / webm / mkv | auto |

E em Download Options:

| Opção | Para que serve | |---|---| | Download Picker Items | baixar cada item de uma galeria (padrão ligado) | | File Name | sobrescreve o nome gerado pelo cobalt | | Include Picker Audio | baixa também o áudio de fundo da galeria |

Formato de saída

O cobalt responde de quatro formas e o node trata todas:

| status | Download File | Get Link | |---|---|---| | tunnel / redirect | 1 item com o arquivo no binário | 1 item com url e filename | | picker | 1 item por foto/vídeo da galeria (+1 do áudio de fundo) | 1 item com o array picker | | local-processing | 1 item com os streams em data0, data1, … | 1 item com o JSON completo | | error | erro do node com o código do cobalt traduzido | idem |

O download é feito em stream, então vídeo grande não estoura a memória do n8n quando o binary data está em modo filesystem.

Erros da API viram mensagens legíveis — content.too_long vira "The media is too long. The duration limit on this instance is 180 minutes" — mantendo o código original na descrição do erro.

Exemplos

Baixar um vídeo do YouTube em 1080p e mandar pro Google Drive

Cobalt YouTube (Download File, Video Quality 1080p) → Google Drive (Upload, campo binário data).

Extrair só o áudio de um TikTok

Cobalt TikTok → Download Mode Audio Only, Options → Audio Format MP3, TikTok Full Audio ligado.

Baixar um carrossel do Instagram

Cobalt Instagram (Download File). Cada foto sai como um item separado, prontos para um loop.

Só o link, sem transferir o arquivo

Qualquer node → operação Get Link. Útil para mandar a URL de tunnel para outro serviço baixar.

Desenvolvimento

npm install
npm run generate:nodes   # regera os 21 nodes e os ícones
npm run build
npm run lint
npm run dev              # sobe um n8n local com os nodes carregados

Os nodes por serviço são gerados. Não edite nodes/Cobalt<Serviço>/ na mão: mude scripts/services.mjs e rode npm run generate:nodes.

credentials/CobaltApi.credentials.ts   credencial compartilhada
nodes/Cobalt/                          node genérico (Media, Instance, Session)
nodes/Cobalt<Serviço>/                 21 nodes gerados
nodes/shared/options.ts                catálogo das opções da API
nodes/shared/transport.ts              HTTP, auth, download em stream
nodes/shared/execute.ts                tunnel / picker / local-processing
nodes/shared/errors.ts                 códigos de erro do cobalt traduzidos
icons/                                 ícones light e dark
scripts/services.mjs                   fonte única dos serviços

Publicar no npm

npm login
npm run release

O pacote é escopado, então já vai com publishConfig.access: public. O prepublishOnly roda a verificação do @n8n/node-cli, que checa as regras de community node exigidas pelo n8n Cloud.

Observações

• Os ícones são marcas geradas (inicial + cor da marca + selo do cobalt), não os logos oficiais, para não redistribuir material de marca de terceiros. Para trocar, substitua os SVGs em icons/.
• Links de tunnel expiram (TUNNEL_LIFESPAN, padrão 90s). Se usar Get Link e baixar depois, baixe rápido ou use Download File.
• Local Processing em preferred/forced devolve streams separados que ainda precisam ser juntados com FFmpeg. Deixe em disabled a não ser que você faça esse merge depois.

Licença

MIT