Os parâmetros de incorporação do YouTube são as opções da query string que controlam exatamente o aspeto e o comportamento de um vídeo incorporado. Este guia percorre doze dos mais úteis, individualmente, com um exemplo funcional para cada um, para que veja precisamente o que cada um altera.
Como os parâmetros se ligam a um URL de incorporação
Cada parâmetro é adicionado ao URL de incorporação como um par chave-valor, unido por um E comercial: https://www.youtube-nocookie.com/embed/VIDEO_ID?param1=value1¶m2=value2. Pode combinar tantos quantos quiser. Os parâmetros do tipo booleano geralmente usam 1 para “ativo” e 0 para “inativo”, e omitir um parâmetro por completo faz com que o YouTube use o seu comportamento predefinido para esse caso.
1. autoplay
Inicia o vídeo assim que o leitor carrega, sem que o visitante prima reproduzir.
https://www.youtube-nocookie.com/embed/VIDEO_ID?autoplay=1A maioria dos navegadores bloqueia a reprodução automática de vídeo com som, a menos que o visitante já tenha interagido com o seu site, pelo que autoplay é quase sempre combinado com mute.
2. mute
Inicia o leitor sem som, o que é o que faz com que o autoplay funcione de forma fiável em todos os navegadores.
https://www.youtube-nocookie.com/embed/VIDEO_ID?autoplay=1&mute=13. start
Inicia a reprodução num número específico de segundos dentro do vídeo, em vez de a partir do início.
https://www.youtube-nocookie.com/embed/VIDEO_ID?start=90Noventa segundos, neste exemplo, significa que o leitor abre diretamente na marca de 1:30.
4. end
Para a reprodução num número específico de segundos, útil para mostrar apenas um excerto relevante de um vídeo mais longo.
https://www.youtube-nocookie.com/embed/VIDEO_ID?start=30&end=90Combinado com start, isto reproduz apenas a janela entre os 30 e os 90 segundos e depois para.
5. loop
Repete o vídeo automaticamente assim que termina. Para um único vídeo (não uma lista de reprodução), também precisa de adicionar um parâmetro playlist definido com o mesmo ID de vídeo, ou a repetição não funcionará silenciosamente.
https://www.youtube-nocookie.com/embed/VIDEO_ID?loop=1&playlist=VIDEO_ID6. controls
Mostra ou oculta a barra de controlo do leitor (reproduzir/pausar, volume, progresso, ecrã inteiro).
https://www.youtube-nocookie.com/embed/VIDEO_ID?controls=0Definir isto como 0 é comum em vídeo estilo fundo, onde não se pretendem controlos de reprodução visíveis.
7. rel
Controla que vídeos relacionados são sugeridos assim que a reprodução termina. Defini-lo como 0 limita as sugestões a vídeos do mesmo canal, em vez do conjunto de recomendações mais amplo do YouTube.
https://www.youtube-nocookie.com/embed/VIDEO_ID?rel=08. list (e o caminho videoseries)
Carrega uma lista de reprodução inteira em vez de um único vídeo. Isto é combinado com o caminho /embed/videoseries em vez de um único ID de vídeo.
https://www.youtube-nocookie.com/embed/videoseries?list=PLAYLIST_ID9. index
Usado juntamente com uma lista de reprodução para escolher em que item começar, contando a partir de 0 para o primeiro vídeo.
https://www.youtube-nocookie.com/embed/videoseries?list=PLAYLIST_ID&index=2Este exemplo começa no terceiro vídeo da lista de reprodução.
10. hl
Define o idioma dos próprios elementos de interface do leitor (não o áudio ou as legendas do vídeo), usando um código de idioma padrão.
https://www.youtube-nocookie.com/embed/VIDEO_ID?hl=de11. cc_load_policy
Força a exibição de legendas por predefinição quando definido como 1, útil para incorporações centradas na acessibilidade ou vídeo em autoplay silencioso onde as legendas transmitem o significado.
https://www.youtube-nocookie.com/embed/VIDEO_ID?cc_load_policy=112. color
Define a cor da barra de progresso do leitor, aceitando red ou white como valores.
https://www.youtube-nocookie.com/embed/VIDEO_ID?color=whiteCombinar vários parâmetros
Os parâmetros combinam-se livremente. Um excerto de fundo respeitador da privacidade, responsivo, com reprodução automática, que se repete em silêncio e oculta os controlos, poderia ter este aspeto:
https://www.youtube-nocookie.com/embed/VIDEO_ID?autoplay=1&mute=1&controls=0&loop=1&playlist=VIDEO_ID&rel=0Tabela de referência
| Parâmetro | Valores | O que faz |
|---|---|---|
| autoplay | 0 / 1 | Inicia a reprodução automaticamente |
| mute | 0 / 1 | Inicia sem som, necessário para autoplay fiável |
| start | segundos | Ponto de início da reprodução |
| end | segundos | Ponto de paragem da reprodução |
| loop | 0 / 1 | Repete o vídeo (precisa do parâmetro playlist para um único vídeo) |
| controls | 0 / 1 | Mostra ou oculta a barra de controlo |
| rel | 0 / 1 | Limita as sugestões de fim de vídeo ao mesmo canal |
| list | ID da lista de reprodução | Carrega uma lista de reprodução completa via /embed/videoseries |
| index | número | Em que item da lista de reprodução começar |
| hl | código de idioma | Idioma da interface do leitor |
| cc_load_policy | 0 / 1 | Ativa as legendas por predefinição |
| color | red / white | Cor da barra de progresso |
Leitura relacionada
Para o lado do layout da incorporação, consulte o nosso guia sobre incorporações responsivas do YouTube. Para privacidade, consulte incorporar vídeos do YouTube sem cookies. Para resolução de problemas, consulte vídeo do YouTube não incorpora: 8 soluções.
Parâmetros frequentemente confundidos entre si
Alguns destes doze parâmetros são suficientemente confundidos entre si para merecerem uma comparação direta. autoplay e loop soam de forma semelhante, mas fazem trabalhos diferentes: autoplay controla se a reprodução começa ao carregar, loop controla se recomeça depois de terminar, e são normalmente usados em conjunto, mas são definições independentes. start e index também são fáceis de confundir: start é um desvio temporal em segundos dentro de um único vídeo, enquanto index é uma posição dentro de uma lista de reprodução, contada em itens em vez de tempo. Emparelhá-los corretamente é importante, já que combiná-los de forma errada (por exemplo, tentar usar index numa incorporação de vídeo único) simplesmente não tem qualquer efeito, em vez de produzir um erro.
Parâmetros com suporte limitado ou inconsistente
Nem todos os parâmetros se comportam de forma idêntica em todos os contextos. modestbranding, que reduz a presença do logótipo do YouTube, tem tido efeitos inconsistentes em diferentes versões do leitor e é geralmente considerado uma definição de melhor esforço, e não garantida. Da mesma forma, alguns parâmetros relacionados com a exibição podem comportar-se de forma ligeiramente diferente consoante o visitante tenha sessão iniciada numa conta Google no navegador, já que as preferências ao nível da conta podem interagir com as predefinições do leitor. Os parâmetros de controlo de reprodução abordados acima, start, end, autoplay, mute, loop e controls, são os mais consistentemente fiáveis em diferentes navegadores e estados de conta, razão pela qual são os que vale a pena usar como base da sua estratégia de incorporação.
Um exemplo prático: construir uma incorporação de página de curso passo a passo
Imagine que está a incorporar um vídeo de aula numa página de curso e quer que seja respeitador da privacidade, responsivo, a começar aos dois minutos, onde começa realmente o conteúdo da aula (saltando uma introdução do canal), com legendas ativas por predefinição para acessibilidade, e sem reprodução automática, já que o visitante deve escolher iniciá-lo. Percorrendo os parâmetros: respeitador da privacidade significa o domínio youtube-nocookie.com; responsivo significa um invólucro baseado em percentagem em vez de dimensões fixas; começar aos dois minutos significa start=120; legendas por predefinição significa cc_load_policy=1; e sem reprodução automática significa simplesmente omitir o parâmetro autoplay, já que esse é o estado predefinido. O URL de incorporação resultante seria:
https://www.youtube-nocookie.com/embed/VIDEO_ID?start=120&cc_load_policy=1&rel=0Este exemplo único mostra como os parâmetros abordados neste guia se combinam naturalmente para resolver um requisito específico e realista, em vez de existirem como uma lista abstrata.
Testar as suas combinações de parâmetros
Antes de publicar uma incorporação com vários parâmetros combinados, vale a pena testá-la diretamente em vez de assumir que a combinação funciona como esperado. Cole o URL de incorporação completo, parâmetros incluídos, diretamente num separador do navegador; o leitor deve comportar-se exatamente como faria dentro do iframe da sua página, o que permite detetar erros de digitação nos nomes dos parâmetros (um erro comum, já que um parâmetro mal escrito é normalmente apenas ignorado silenciosamente, em vez de assinalado como erro) antes de chegarem ao seu site em produção.
Parâmetros e privacidade: quais interagem com o domínio nocookie
Vale a pena esclarecer que todos os parâmetros abordados neste guia funcionam de forma idêntica quer use o domínio de incorporação padrão youtube.com quer o domínio com privacidade reforçada youtube-nocookie.com. A escolha do domínio e os parâmetros de reprodução são decisões totalmente independentes: mudar para o domínio com privacidade reforçada não desativa nem altera nenhum de autoplay, mute, start, end, loop, controls, rel, list, index, hl, cc_load_policy ou color. Este é um ponto de confusão comum que vale a pena esclarecer diretamente, já que alguns proprietários de sites assumem que o modo de privacidade é uma versão reduzida do leitor com menos opções, quando, na prática, é funcionalmente idêntico, apenas com um comportamento de cookies diferente do lado da Google.
Criar a sua própria referência de parâmetros para um projeto específico
Para um site maior com muitos vídeos incorporados, vale a pena documentar internamente qual combinação destes doze parâmetros a sua equipa usa por predefinição, em vez de reinventar a escolha para cada nova incorporação. Um padrão interno simples, por exemplo: usar sempre o domínio com privacidade reforçada, incluir sempre rel=0, não usar reprodução automática por predefinição, a menos que um tipo específico de página o exija, e usar sempre um invólucro responsivo, mantém as incorporações consistentes em todo o site e torna muito mais rápido identificar uma mal configurada durante uma revisão. Tratar esta lista de doze parâmetros como um menu de onde escolher predefinições, em vez de uma decisão avulsa tomada de raiz sempre que necessário, compensa à medida que o conteúdo em vídeo de um site cresce.
Uma palavra final sobre manter esta referência à mão
Guardar esta página nos favoritos, ou especificamente a tabela de referência acima, é provavelmente mais útil do que tentar memorizar todos os doze parâmetros de uma vez. Na prática, a maioria das incorporações num site típico usa apenas três ou quatro destes em simultâneo (normalmente um domínio com privacidade reforçada de forma implícita, rel=0, e ocasionalmente start ou autoplay/mute em conjunto), pelo que ter a lista completa para consultar nos casos menos comuns, como listas de reprodução ou legendas, cobre as restantes situações sem ser necessário memorizar tudo antecipadamente.
Como a documentação do próprio YouTube se compara a este guia
O YouTube publica a sua própria documentação para programadores, abrangendo a IFrame Player API e os parâmetros de incorporação, dirigida principalmente a programadores que constroem leitores personalizados, controlados por JavaScript, em vez de proprietários de sites que apenas adicionam uma incorporação simples a uma página. Este guia foca-se especificamente no subconjunto de parâmetros relevantes para uma incorporação iframe padrão sem JavaScript personalizado, o que cobre a grande maioria dos casos de uso reais em sites comuns. Para quem está a construir experiências de vídeo mais avançadas e controladas por programação (botões de reprodução personalizados, monitorização do progresso de visualização, leitores multi-vídeo sincronizados), a documentação da própria IFrame Player API do YouTube é o passo seguinte, além do que uma abordagem baseada em parâmetros de query string como esta pode oferecer.
Um resumo final dos doze parâmetros
Entre autoplay, mute, start, end, loop, controls, rel, list, index, hl, cc_load_policy e color, a conclusão prática é que um pequeno punhado (a escolha do domínio de privacidade, rel e um invólucro responsivo) forma uma predefinição sensata para quase todas as incorporações, enquanto o resto (start/end, loop, formatação de shorts, listas de reprodução, legendas, idioma e cor) são ferramentas situacionais que vale a pena usar apenas quando uma página específica realmente o exige, em vez de serem adicionadas indiscriminadamente a todas as incorporações de um site.
Crie uma agora
Ferramenta gratuita
Salte as query strings manuais. Cole um link e ative as opções de que precisa.
Manter esta referência à mão significa nunca ter de adivinhar nomes de parâmetros de memória quando surge uma nova necessidade de incorporação.
Perguntas frequentes
Todos estes parâmetros funcionam em conjunto sem conflitos?
Sim, geralmente podem ser combinados livremente. A principal dependência a lembrar é que loop precisa de um parâmetro playlist correspondente para funcionar num único vídeo.
Existem parâmetros que já não funcionam?
Alguns parâmetros mais antigos, referenciados em tutoriais antigos, como showinfo, foram descontinuados pelo YouTube ao longo do tempo e já não têm qualquer efeito visível.
Preciso de memorizar isto para os usar?
Não. O nosso gerador de código de incorporação gratuito apresenta os mais úteis como simples interruptores e campos, e constrói o URL por si.
O que acontece se escrever mal o nome de um parâmetro?
O leitor do YouTube geralmente ignora os parâmetros que não reconhece, em vez de gerar um erro visível, pelo que um erro de digitação simplesmente não tem efeito, razão pela qual vale a pena testar diretamente o URL exato da sua incorporação.
Posso definir um nível de volume predefinido com um parâmetro?
Não, não existe um parâmetro para um nível de volume predefinido específico; o leitor inicia sem som (através do parâmetro mute) ou com a última definição de volume usada pelo próprio espetador.
Estes parâmetros funcionam da mesma forma em dispositivos móveis?
Geralmente sim, embora os navegadores móveis apliquem as suas próprias restrições adicionais de reprodução automática, para além das do próprio YouTube, pelo que o autoplay sem som é ainda mais consistentemente necessário em dispositivos móveis do que em computadores.
Posso alterar estes parâmetros depois de um vídeo já estar incorporado na minha página?
Sim, já que os parâmetros vivem simplesmente no URL src do iframe, editar o HTML da sua página e republicar tem efeito imediato para quem carregar a página posteriormente.
Existe um número máximo de parâmetros que posso combinar?
Sem limite prático; os URLs podem conter muitos parâmetros, e todos os doze abordados aqui podem, tecnicamente, ser combinados numa única incorporação em simultâneo, embora nem todas as combinações façam sentido em conjunto.