<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  <!ENTITY kid3 '<application
>Kid3</application
>'>
  <!ENTITY doublehyphen '--'>
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % Portuguese "INCLUDE"
><!-- change language only here -->
]>
<book lang="&language;" id="kid3-handbook">

<bookinfo>
<title
>O Manual do &kid3;</title>

<authorgroup>
<author
><firstname
>Urs</firstname
> <surname
>Fleisch</surname
> <affiliation
> <address
><email
>ufleisch@users.sourceforge.net</email
></address>
</affiliation>
<contrib
>Desenvolvimento da aplicação</contrib>
</author>

<othercredit role="translator"
><firstname
>José</firstname
><surname
>Pires</surname
><affiliation
><address
><email
>zepires@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</authorgroup>

<copyright>
<year
>2021</year>
<holder
>Urs Fleisch</holder>
</copyright>
<legalnotice id="fdl-notice"
>&FDLNotice;</legalnotice>

<date
>2021-03-18</date>
<releaseinfo
>3.8.6</releaseinfo>

<abstract>
<para
>O &kid3; é uma aplicação para editar as marcas de ID3v1 e ID3v2 nos ficheiros MP3 de forma eficiente. Da mesma forma, também são suportadas as marcas nos ficheiros Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF e módulos do Tracker (MOD, S3M, IT, XM). É fácil configurar as marcas de vários ficheiros com os mesmos valores (<abbrev
>p.ex.</abbrev
> álbum, artista, ano e género em todos os ficheiros do mesmo álbum) e gerar as marcas a partir do nome do ficheiro ou vice-versa. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdemultimedia</keyword>
<keyword
>MP3</keyword>
<keyword
>ID3</keyword>
<keyword
>ID3v1</keyword>
<keyword
>ID3v2</keyword>
<keyword
>Ogg</keyword>
<keyword
>Vorbis</keyword>
<keyword
>FLAC</keyword>
<keyword
>MPC</keyword>
<keyword
>APE</keyword>
<keyword
>Musepack</keyword>
<keyword
>MP4</keyword>
<keyword
>M4A</keyword>
<keyword
>MP2</keyword>
<keyword
>Speex</keyword>
<keyword
>TrueAudio</keyword>
<keyword
>WavPack</keyword>
<keyword
>WMA</keyword>
<keyword
>WAV</keyword>
<keyword
>AIFF</keyword>
<keyword
>MOD</keyword>
<keyword
>S3M</keyword>
<keyword
>IT</keyword>
<keyword
>XM</keyword>
<keyword
>Opus</keyword>
<keyword
>DSF</keyword>
</keywordset>

</bookinfo>

<!--begin manpage include
<refmeta>
<refentrytitle
>kid3</refentrytitle>
<manvolnum
>1</manvolnum>
</refmeta>

<refnamediv>
<refname
>kid3</refname>
<refname
>kid3-qt</refname>
<refname
>kid3-cli</refname>
<refpurpose
>Kid3 ID3 Tagger</refpurpose>
</refnamediv>
end manpage include-->

<!--change manpage<refsynopsisdiv
>--><preface id="synopsis"
><title
>Sintaxe</title>
<cmdsynopsis
><command
>kid3</command
> <group
> <arg choice="plain"
><option
>&doublehyphen;help</option
></arg
> <arg choice="plain"
><option
>&doublehyphen;author</option
></arg
> <arg choice="plain"
><option
>&doublehyphen;version</option
></arg
> <arg choice="plain"
><option
>&doublehyphen;license</option
></arg
> <arg choice="plain"
><option
>&doublehyphen;desktopfile <filename
>FICHEIRO</filename
></option
></arg
> </group
> <arg rep="repeat"
><replaceable
>FICHEIRO</replaceable
></arg
> </cmdsynopsis>
<cmdsynopsis
><command
>kid3-qt</command
> <arg
><option
>&doublehyphen;portable</option
></arg
> <arg
><option
>opções do Qt</option
></arg
> <arg rep="repeat"
><replaceable
>FICHEIRO</replaceable
></arg
> </cmdsynopsis>
<cmdsynopsis
><command
>kid3-cli</command
> <arg
><option
>&doublehyphen;portable</option
></arg
> <arg
><option
>&doublehyphen;dbus</option
></arg
> <group
> <arg choice="plain"
><option
>-h</option
></arg
> <arg choice="plain"
><option
>&doublehyphen;help</option
></arg
> </group
> <arg
><option
>-c COMANDO1</option
></arg
> <arg rep="repeat"
><option
>-c COMANDO2</option
></arg
> <arg rep="repeat"
><replaceable
>FICHEIRO</replaceable
></arg
> </cmdsynopsis>
<!--change manpage</refsynopsisdiv
>--></preface>

<preface id="options"
><title
>Opções</title>

<variablelist>
<varlistentry>
<term
><option
>&doublehyphen;portable</option
></term>
<listitem
><para
>Guarda a configuração no ficheiro <filename
>kid3.ini</filename
> dentro da pasta da aplicação.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><replaceable
>FICHEIRO</replaceable
></term>
<listitem
><para
>Se o <filename
><replaceable
>FICHEIRO</replaceable
></filename
> for a localização de uma pasta, a mesma será aberta. Se forem indicados um ou mais ficheiros, a sua pasta comum é aberta, ficando os ficheiros seleccionados. </para
></listitem>
</varlistentry>
</variablelist>

<sect1 id="options-kid3"
><title
>kid3</title>
<variablelist>
<varlistentry>
<term
><option
>&doublehyphen;help</option
></term>
<listitem
><para
>Mostra a ajuda acerca das opções.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><option
>&doublehyphen;author</option
></term>
<listitem
><para
>Mostra informações sobre o autor.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><option
>&doublehyphen;version</option
></term>
<listitem
><para
>Mostra a informação da versão.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><option
>&doublehyphen;license</option
></term>
<listitem
><para
>Mostra informações acerca da licença.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><option
>&doublehyphen;desktopfile <filename
>FICHEIRO</filename
></option
></term>
<listitem
><para
>O nome de base do ficheiro do item '.desktop' para esta aplicação.</para
></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="options-kid3-qt"
><title
>kid3-qt</title>
<variablelist>
<varlistentry>
<term
><option
>Opções do Qt</option
></term>
<listitem
><para
>Veja o <citerefentry
><refentrytitle
>qt5options</refentrytitle
> <manvolnum
>7</manvolnum
></citerefentry
>.</para
></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="options-kid3-cli"
><title
>kid3-cli</title>
<variablelist>

<varlistentry>
<term
><option
>&doublehyphen;dbus</option
></term>
<listitem
><para
>Activa a interface de &DBus;.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><option
>-c</option
></term>
<listitem
><para
>Executa um comando. É possível passar várias opções <option
>-c</option
>, sendo as mesmas executadas em sequência. Veja a secção acerca do <link linkend="kid3-cli"
>kid3-cli</link
> para obter uma descrição dos comandos disponíveis.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><option
>-h</option
>|<option
>&doublehyphen;help</option
></term>
<listitem
><para
>Mostra ajuda sobre as opções e comandos.</para
></listitem>
</varlistentry>

</variablelist>
</sect1>

</preface>

<chapter id="introduction">
<title
>Introdução</title>

<para
>O &kid3; é uma aplicação para editar as marcas ID3v1 e ID3v2 nos ficheiros MP3 de forma eficiente. Estas marcas poderão ser editadas pela maioria dos leitores de MP3, mas não de forma confortável e eficiente. Para além disso, também são suportadas as marcas nos ficheiros Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF e nos módulos do Tracker (MOD, S3M, IT, XM). </para>
<para
>O &kid3; não captura nem codifica os ficheiros MP3, mas está vocacionado para editar as marcas de ID3 de todos os ficheiros de um álbum de forma eficiente, &ie; com o mínimo de 'clicks' de rato e combinações de teclas possível. Embora a maioria dos outros programas consigam editar as marcas de ID3v1 ou ID3v2, o &kid3; tem controlo completo sobre ambas as versões, consegue converter as marcas entre os dois formatos e tem acesso a todas as marcas de ID3v2. As marcas dos vários ficheiros poderão ser configuradas com o mesmo valor, <abbrev
>p.ex.</abbrev
> o artista, o álbum, o ano e o género de todos os ficheiros de um álbum tipicamente têm os mesmos valores e poderão ser definidas em conjunto. Se a informação das marcas estiver contida no nome do ficheiro, as marcas poderão ser configuradas automaticamente a partir do nome do ficheiro. Também é possível configurar o nome do ficheiro de acordo com as marcas encontras no ficheiro em formatos arbitrários. </para>
<para
>A tarefa de edição ainda passa pela substituição automática de caracteres ou sub-textos, por exemplo para remover caracteres proibidos dos nomes dos ficheiros. O controlo automático das maiúsculas ou minúsculas facilita a utilização de uma nomenclatura consistente em todas as marcas. </para>
<para
>Poderá obter a informação das marcas para álbuns inteiros a partir do <ulink url="http://gnudb.org"
>gnudb.org</ulink
>, <ulink url="http://musicbrainz.org"
>MusicBrainz</ulink
>, <ulink url="http://discogs.com"
>Discogs</ulink
>, <ulink url="http://www.amazon.com"
>Amazon</ulink
> ou de outras fontes de listas de faixas. O formato de configuração é facilmente configurável à custa de expressões regulares. </para>
<para
>Por favor comunique todos os problemas ou pedidos de funcionalidades ao autor. </para>
</chapter>

<chapter id="using-kid3">
<title
>Utilização do &kid3;</title>

<sect1 id="kid3-features">
<title
>Funcionalidades do &kid3;</title>
<itemizedlist>
<listitem
><para
>Editar as marcas de ID3v1.1</para
></listitem>
<listitem
><para
>Editar todos os pacotes de ID3v2.3 e ID3v2.4</para
></listitem>
<listitem
><para
>Editar as marcas de vários ficheiros</para
></listitem>
<listitem
><para
>Converter as marcas entre ID3v1 e ID3v2</para
></listitem>
<listitem
><para
>Editar as marcas de MP3, Ogg/Vorbis, Opus, DSF, FLAC, MPC, APE, MP4/AAC, MP2, Speex, TrueAudio, WavPack, WMA, WAV e AIFF</para
></listitem>
<listitem
><para
>Gerar as marcas a partir do nome do ficheiro</para
></listitem>
<listitem
><para
>Gerar marcas a partir dos conteúdos dos campos de marcas</para
></listitem>
<listitem
><para
>Gerar o nome do ficheiro a partir das marcas</para
></listitem>
<listitem
><para
>Gerar e mudar os nomes das pastas a partir das marcas</para
></listitem>
<listitem
><para
>Gerar um ficheiro de lista de reprodução</para
></listitem>
<listitem
><para
>Conversão automática de capitalização e traduções de textos</para
></listitem>
<listitem
><para
>Importação das fontes de dados <ulink url="http://gnudb.org"
>gnudb.org</ulink
>, <ulink url="http://musicbrainz.org"
>MusicBrainz</ulink
>, <ulink url="http://discogs.com"
>Discogs</ulink
>, <ulink url="http://www.amazon.com"
>Amazon</ulink
>, entre outras.</para
></listitem>
<listitem
><para
>Exportar como CSV, &HTML;, lista de reprodução, Kover &XML; e outros formatos. Os ficheiros CSV podem ser importados de novo.</para
></listitem>
</itemizedlist>
</sect1>

<sect1 id="example-usage">
<title
>Exemplo de Utilização</title>
<para
>Esta secção descreve uma típica sessão com o &kid3;. Vamos assumir que temos uma pasta que contém ficheiros MP3 com as faixas do álbum "Vamos Marcar" da banda "Famoso Desconhecido". A pasta tem o nome no formato "artista - álbum", sendo no nosso caso <filename
>Famoso Desconhecido - Vamos Marcar</filename
>. A pasta contém as faixas no formato "faixa título.mp3", o que poderá ser útil porque os nomes dos ficheiros são curtos (é importante quando estiver a usar leitores de MP3 portáteis com ecrãs pequenos) e fica pela ordem correcta quando for ordenado por ordem alfabética (importante ao usar leitores de MP3 por 'hardware', que tocam os MP3 por ordem alfabética ou pela ordem com que são gravados no &CD;, ficando essa ordem alfabética ao usar o <command
>mkisofs</command
>). Para além disso, a informação do artista e do álbum já está no nome da pasta e não tem de ser repetida no nome do ficheiro. Contudo, voltando ao nosso exemplo, a listagem da pasta deverá ser algo semelhante a isto: </para>
<para
><filename
>01 Intro.mp3</filename
></para>
<para
><filename
>02 So Temos Este.mp3</filename
></para>
<para
><filename
>03 Final.mp3</filename
></para>
<para
>Estes ficheiros ainda não têm marcas e desejamos gerá-las com o &kid3;. Use a opção <guimenuitem
>Abrir</guimenuitem
> (menu <guimenu
>Ficheiro</guimenu
> ou barra de ferramentas) e seleccione um dos ficheiros nesta pasta. Todos os ficheiros serão apresentados na lista de ficheiros. Para facilitar, pretende-se usar esta informação no nome das pastas e dos ficheiros para gerar marcas. Como tal, serão seleccionados todos os ficheiros, podendo carregar depois no botão <guilabel
>Para:</guilabel
> <guibutton
>Marca 1</guibutton
> na secção <guilabel
>Ficheiro</guilabel
>. Isto irá definir os valores do título, do artista, do álbum e da faixa para todos os ficheiros. Para configurar os valores do ano e do género de todos os ficheiros, são mantidos todos os ficheiros seleccionados, podendo depois escrever "2002" na <guilabel
>Data</guilabel
> e seleccionando "Pop" na lista <guilabel
>Género</guilabel
>. Para configurar apenas estes dois valores, as suas opções de marcação ficam automaticamente assinaladas e todas as outras opções de marcação são deixadas inalteradas. Agora, será alterada a selecção, seleccionando apenas o primeiro ficheiro e vendo que todas as marcas contêm os valores correctos. Poderá verificar as marcas dos outros ficheiros da mesma forma se as seleccionar uma a uma. Quando estiver satisfeito com as marcas, poderá usar a opção <guimenuitem
>Gravar</guimenuitem
> (menu <guimenu
>Ficheiro</guimenu
> ou barra de ferramentas). Se seleccionar a opção <guimenuitem
>Criar uma Lista de Reprodução</guimenuitem
> do menu <guimenu
>Ficheiro</guimenu
> para gerar um ficheiro <filename
>Famoso Desconhecido - Vamos Marcar.m3u</filename
> na pasta. </para>
</sect1>

</chapter>

<chapter id="commands">
<title
>Referência de Comandos</title>

<sect1 id="gui-elements">
<title
>Os Elementos da &GUI;</title>
<para
>A interface &GUI; do &kid3; está separada em seis secções: À esquerda encontra-se a lista de ficheiros e pastas, enquanto o lado direito contém as secções <guilabel
>Ficheiro</guilabel
>, <guilabel
>Marca 1</guilabel
>, <guilabel
>Marca 2</guilabel
> e <guilabel
>Marca 3</guilabel
>. </para>

<para
>Para navegar pelas diferentes secções com o teclado, são suportadas diversas combinações de teclas. Nas secções das marcas, os atalhos ficam activos quando não estiver a editar texto ou quando estiver na primeira coluna. <itemizedlist>
<listitem
><para
><keycombo
>&Alt;<keycap
>Esquerda</keycap
></keycombo
>: Vai para a secção anterior (<keycombo
><keycap
>Command</keycap
><keycap
>[</keycap
></keycombo
> no &macOS;) </para
></listitem>
<listitem
><para
><keycombo
>&Alt;<keycap
>Direita</keycap
></keycombo
>: Vai para a secção seguinte (<keycombo
><keycap
>Command</keycap
><keycap
>]</keycap
></keycombo
> no &macOS;) </para
></listitem>
<listitem
><para
><keycombo
>&Ctrl;<keycap
>Shift</keycap
><keycap
>V</keycap
></keycombo
>: De outra marca </para
></listitem>
<listitem
><para
><keycombo
>&Ctrl;<keycap
>C</keycap
></keycombo
>: Copiar </para
></listitem>
<listitem
><para
><keycombo
>&Ctrl;<keycap
>V</keycap
></keycombo
>: Colar </para
></listitem>
<listitem
><para
><keycombo
><keycap
>Shift</keycap
><keycap
>Delete</keycap
></keycombo
>: Remover </para
></listitem>
<listitem
><para
><keycombo
><keycap
>F2</keycap
></keycombo
>: Editar </para
></listitem>
<listitem
><para
><keycombo
><keycap
>Insert</keycap
></keycombo
>: Adicionar </para
></listitem>
<listitem
><para
><keycombo
><keycap
>Delete</keycap
></keycombo
>: Apagar </para
></listitem>
</itemizedlist>
</para>

<sect2 id="file-list">
<title
>Lista de Ficheiros</title>

<para
>A lista de ficheiros contém os nomes de todos os ficheiros na pasta aberta que correspondam ao filtro de nomes de ficheiros seleccionados (tipicamente o <filename class="extension"
>*.mp3 *.ogg *.opus *.dsf *.flac *.mpc *.aac *.m4a *.m4b *.m4p *.mp4 *.mp2 *.spx *.tta *.wv *.wma *.wav *.aiff *.ape</filename
>). Poderá ser seleccionado um ou vários ficheiros. Para não seleccionar nenhum ficheiro, carregue na área vazia a seguir aos itens da lista. A selecção determina os ficheiros que são afectados pelas operações que ficam disponíveis através dos botões descritos em baixo. </para>
<para
>Para além do <guilabel
>Nome</guilabel
>, também poderá mostrar as outras colunas <guilabel
>Tamanho</guilabel
>, <guilabel
>Tipo</guilabel
>, <guilabel
>Data de Modificação</guilabel
> com os detalhes dos ficheiros. Poderá esconder as colunas, desmarcando o nome das mesmas no menu de contexto que existe no cabeçalho da lista. A ordem das colunas pode ser alterada por arrastamento. O sentido de ordenação poderá ser comutado se carregar no cabeçalho da coluna. </para>
<para
>À esquerda dos nomes, poderá aparecer um ícone: um disco para indicar que o ficheiro modificado ou informações sobre as marcas que estão presentes (V1, V2, V1V2 ou SEM MARCAS - não é apresentado nenhum ícone se o ficheiro ainda não tiver sido lido). </para>
<para
>As pastas são apresentadas com um ícone de pasta. Se abrir uma pasta, os seus ficheiros são apresentados numa árvore hierárquica. Ao seleccionar os ficheiros das sub-pastas, poderá efectuar operações sobre os ficheiros das diferentes pastas, o que é útil se a colecção de música estiver organizadas com uma pasta para cada artista, contendo pastas para os álbuns desse artista. </para>
<para
>Se carregar com o <mousebutton
>botão direito</mousebutton
> do rato dentro da lista de ficheiros, irá abrir um menu de contexto com os seguintes comandos: <itemizedlist>
<listitem
><para
><guimenuitem
>Expandir tudo</guimenuitem
>: Expande todas as árvores de pastas (só a árvore actual se estiver a carregar na tecla <keycap
>Shift</keycap
>) </para
></listitem>
<listitem
><para
><guimenuitem
>Fechar tudo</guimenuitem
>: Fecha todas as árvores de pastas </para
></listitem>
<listitem
><para
><guimenuitem
>Mudar o Nome</guimenuitem
>: Muda o nome de um ficheiro </para
></listitem>
<listitem
><para
><guimenuitem
>Enviar para o Lixo</guimenuitem
>: Move um ficheiro para o lixo </para
></listitem>
<listitem
><para
><guimenuitem
>Reproduzir</guimenuitem
>: Reproduz um ficheiro; veja a secção <link linkend="play"
>Reproduzir</link
>. Se o ficheiro seleccionado for uma lista de reprodução, então serão reproduzidos os ficheiros na lista de reprodução. </para
></listitem>
<listitem
><para
><guimenuitem
>Editar</guimenuitem
>: Edita uma lista de reprodução; veja a secção  <link linkend="edit-playlist"
>Editar a Lista de Reprodução</link
>. </para
></listitem>
<listitem
><para
>Os itens seguintes são comandos do utilizador, os quais podem ser definidos na página de <guilabel
>Acções do Utilizador</guilabel
> do <link linkend="configure-kid3"
>Configurar o &kid3;</link
>. A reprodução através de duplo-click pode também ser activada aí. </para
></listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="edit-playlist">
<title
>Editar a Lista de Reprodução</title>

<para
>Poderá criar uma lista de reprodução vazia ou a conter as faixas de uma determinada pasta; veja como <link linkend="create-playlist"
>Criar uma Lista de Reprodução</link
>. O ficheiro da lista de reprodução criado dessa forma poderá ser editado com um duplo-click ou usando a opção <guilabel
>Editar</guilabel
> do menu de contexto da lista de ficheiros. Será apresentada uma janela com os elementos da lista de reprodução. É possível abrir várias listas de reprodução em simultâneo. </para>
<para
>Poderá adicionar novos itens por arrastamento a partir da lista de ficheiros, de um gestor de ficheiros ou de outra lista de reprodução. Se for arrastado um item de outra lista de reprodução, o mesmo será movido ou copiado de acordo com o sistema. Para invocar a outra operação, respectivamente, terá de manter carregada a tecla &Shift;, &Ctrl; ou &Alt; (para copiar em vez de mover no &macOS;). A reordenação de itens dentro da lista também é possível por arrastamento. Em alternativa, os itens podem ser movidos com os atalhos de teclado <keycombo
>&Ctrl;&Shift;<keycap
>Cima</keycap
></keycombo
> e <keycombo
>&Ctrl;&Shift;<keycap
>Baixo</keycap
></keycombo
> (no &macOS; terá de carregar no <keycap
>Command</keycap
> em vez do &Ctrl;). Poderá remover um item se usar a tecla <keycap
>Delete</keycap
>. </para>
<para
>Repare por favor no seguinte: Para arrastar itens da lista de ficheiros, os mesmos terão de ser mantidos do lado esquerdo (perto dos ícones), sendo que o mesmo gesto do lado direito irá efectuar uma selecção múltipla, para que esta acção seja possível e simples. </para>
<para
>Quando tiver modificado uma lista de reprodução, as alterações poderão ser guardadas com o botão <guibutton
>Gravar</guibutton
> ou eliminadas com o <guibutton
>Cancelar</guibutton
>. Quando a janela for fechada, será apresentada uma mensagem de confirmação caso existam modificações por gravar. </para>
<para
>As faixas seleccionadas numa lista de reprodução ficarão automaticamente seleccionadas na lista de ficheiros, podendo deste modo editar as suas marcas. </para>
<para
>Para executar acções sobre uma lista de reprodução, o seu ficheiro deverá estar seleccionado na lista de ficheiros. O <guimenuitem
>Editar</guimenuitem
> do menu de contexto irá conduzir à janela descrita nesta secção, enquanto o <guimenuitem
>Reproduzir</guimenuitem
> irá iniciar o leitor multimédia com as faixas da lista de reprodução. As acções do utilizador poderão actuar sobre as listas de reprodução, como por <link linkend="qml-examples"
>exemplo</link
> o <guilabel
>Exportar a Pasta da Lista de Reprodução</guilabel
>, qur irá copiar os ficheiros de uma lista de reprodução para uma pasta. </para>
</sect2>

<sect2 id="directory-list">
<title
>Lista de Pastas</title>

<para
>A lista de pastas contém os nomes das pastas na pasta aberta de momento, assim como a própria (<filename class="directory"
>.</filename
>) e a sua pasta-mãe (<filename class="directory"
>..</filename
>). Permite a mudança fácil de pasta sem ter de usar o comando <guimenuitem
>Abrir...</guimenuitem
> ou o arrastamento. </para>
<para
>A visibilidade, ordem e sentido de ordenação poderão ser configurados da forma descrita na secção sobre a <link linkend="file-list"
>lista de ficheiros</link
>. </para>
</sect2>

<sect2 id="file">
<title
>Ficheiro</title>

<para
>Mostra informações sobre a codificação (MP3, Ogg, Opus, DSF, FLAC, MPC, APE, MP2, MP4, AAC, Speex, TrueAudio, WavPack, WMA, WAV, AIFF), taxa de dados, taxa de amostragem, os canais e o tamanho do ficheiro. </para>
<para
>O campo de texto <guilabel
>Nome</guilabel
> contém o nome do ficheiro (se só estiver um único ficheiro seleccionado). Se este nome for alterado, o ficheiro irá mudar de nome quando for usado o comando Gravar. </para>
<para
>A lista <guilabel
>Formato</guilabel
> e o campo de texto contém o formato a ser usado quando o nome do ficheiro for gerado a partir da primeira ou segunda marca. O nome do ficheiro poderá conter caracteres arbitrários, podendo incluir uma componente de sub-pastas separadas por uma barra face ao nome do ficheiro, se bem que essa pasta já deva existir para a mudança de nome ser bem sucedida. São usados os seguintes códigos especiais para inserir os valores das marcas no nome do ficheiro: </para>

<itemizedlist>
<listitem
><para
>%s %{title} Título (Música)</para
></listitem>
<listitem
><para
>%a %{artist} Artista</para
></listitem>
<listitem
><para
>%l %{album} Álbum</para
></listitem>
<listitem
><para
>%c %{comment} Comentário</para
></listitem>
<listitem
><para
>%y %{year} Ano</para
></listitem>
<listitem
><para
>%t %{track} Faixa (<abbrev
>p.ex.</abbrev
> 01)</para
></listitem>
<listitem
><para
>%t %{track.n} Faixa com o tamanho do campo 'n' (<abbrev
>p.ex.</abbrev
> 001 para %{track.3})</para
></listitem>
<listitem
><para
>%T %{tracknumber} Faixa (sem os zeros iniciais, <abbrev
>p.ex.</abbrev
> 1)</para
></listitem>
<listitem
><para
>%g %{genre} Género</para
></listitem>
<listitem
><para
>%{ignore} Ignorado quando gerar marcas a partir do nome do ficheiro</para
></listitem>
</itemizedlist>

<para
>Os códigos de formato não estão restritos aos exemplos apresentados acima. Pode usar qualquer nome de pacote, como os nomes de pacotes unificados, por exemplo <userinput
>%{albumartist}</userinput
>, <userinput
>%{discnumber.1}</userinput
>, <userinput
>%{bpm}</userinput
> ou nomes específicos do formato, como <userinput
>%{popm}</userinput
>. </para>

<para
>É possível anteceder e adicionar textos ao substituto de um código de formato, adicionando-os entre aspas dentro das chavetas do código de formato. Estes textos só serão colocados no texto resultante se o código do formato tiver um valor não-vazio. Por exemplo, se o nome do ficheiro deve conter tanto o título como o sub-título, uma pessoa poderá usar o <userinput
>%{title} [%{subtitle}]</userinput
> no texto do formato. Contudo, isto poderia resultar num texto que termina em <computeroutput
> []</computeroutput
> se não existir nenhum pacote de sub-título para um dado ficheiro. Para omitir os parêntesis rectos caso não esteja presente nenhum sub-título, o <userinput
>%{title}%{" ["subtitle"]"}</userinput
> deverá ser usado como alternativa. Isto irá omitir os parêntesis rectos, o espaço inicial e o sub-título se este último não existir. </para>

<para
>A lista de formatos disponíveis poderá ser editada na janela que aparece quando carregar no botão <guibutton
>Nome do ficheiro a partir da marca</guibutton
> da página <guilabel
>Ficheiro</guilabel
> da <link linkend="configure-kid3"
>configuração</link
>. </para>

<para
>É usada uma segunda lista <guilabel
>Formato</guilabel
> (com uma seta para baixo) para gerar as marcas a partir do nome do ficheiro. Se o formato do nome do ficheiro não corresponder a este padrão, serão testados alguns outros formatos usados de forma comum. </para>

<para
>Alguns dos campos normalmente usados já estão na lista, mas também é possível escrever algum formato especial no campo de edição. </para>

<para
>A lista de formatos disponíveis poderá ser editada na janela que aparece quando carregar no botão <guibutton
>Marca a partir do nome do ficheiro</guibutton
> da página <guilabel
>Ficheiro</guilabel
> da <link linkend="configure-kid3"
>configuração</link
>. </para>

<para
>Internamente, uma expressão regular é composta a partir dos códigos do formato. Se forem necessárias expressões regulares avançadas, o formato para gerar as marcas a partir dos nomes dos ficheiros pode ser indicado como uma expressão regular completa com capturas, as quais são antecedidas dos códigos de formato; <abbrev
>p.ex.</abbrev
>, par extrair os números das faixas sem remover os zeros inicias, poderá usar um formato como por exemplo "<userinput
>/%{track}(\d+) %{title}(.*)</userinput
>". </para>
<para
><guilabel
>De:</guilabel
> <guibutton
>Marca 1</guibutton
>, <guibutton
>Marca 2</guibutton
>: Define o nome do ficheiro com o formato seleccionado e a primeira ou segundo marcas, respectivamente. </para>
<para
><guilabel
>Para:</guilabel
> <guibutton
>Marca 1</guibutton
>, <guibutton
>Marca 2</guibutton
>: As marcas são definidas a partir do nome do ficheiro. Em primeiro lugar, será usado o formato definido em <guilabel
>Formato</guilabel
>. Se o nome do ficheiro existente não corresponder a este formato, serão testados os seguintes formatos: </para>
<itemizedlist>
<listitem
><para
><filename
>Artista - Álbum/Número Música</filename
></para
></listitem>
<listitem
><para
><filename
>Álbum/Número - Artista - Música</filename
></para
></listitem>
<listitem
><para
><filename
>/Artista - Álbum - Número - Música</filename
></para
></listitem>
<listitem
><para
><filename
>Álbum/Artista - Número - Música</filename
></para
></listitem>
<listitem
><para
><filename
>Álbum/Artista - Música</filename
></para
></listitem>
<listitem
><para
><filename
>Artista/Álbum/Número Música</filename
></para
></listitem>
</itemizedlist>
<para
>Se for seleccionado apenas um ficheiro, os controlos da &GUI; são preenchidos com os valores do nome do ficheiro. Se forem seleccionados vários ficheiros, as marcas dos ficheiros são configuradas directamente. </para>
</sect2>

<sect2 id="tag1">
<title
>Marca 1</title>

<para
>Os campos de texto do <guilabel
>Título</guilabel
>, <guilabel
>Artista</guilabel
>, <guilabel
>Álbum</guilabel
>, <guilabel
>Comentário</guilabel
>, <guilabel
>Data</guilabel
>, <guilabel
>Número de Faixa</guilabel
> e <guilabel
>Género</guilabel
> são usados para editar o valor correspondente na primeira marca dos ficheiros seleccionados. O valor será alterado quando a selecção de ficheiros mudar ou antes de algumas operações como a <guimenuitem
>Gravar</guimenuitem
> ou <guimenuitem
>Sair</guimenuitem
> e quando a opção de marcação correspondente à esquerda do nome do campo estiver assinalada. Isto é útil para mudar apenas alguns valores e deixar os outros valores inalterados. </para>
<para
>Se estiver seleccionado um único ficheiro, todas as opções de marcação estão assinaladas e os campos de texto contêm os valores encontrados nas marcas deste ficheiro. Se não existir uma dada marca no ficheiro, o valor vazio correspondente é apresentado, o qual é um texto vazio para o <guilabel
>Título</guilabel
>, <guilabel
>Artista</guilabel
>, <guilabel
>Álbum</guilabel
> e <guilabel
>Comentário</guilabel
>, ou 0 para os campos numéricos da <guilabel
>Data</guilabel
> e <guilabel
>Número da Faixa</guilabel
> e um valor seleccionado em branco para a lista  <guilabel
>Género</guilabel
>. Os valores podem ser alterados e, caso a opção de marcação correspondente esteja assinalada, serão configurados para o ficheiro seleccionado após modificar a selecção. O ficheiro fica então marcado como modificado com um símbolo de disco na lista de ficheiros, mas permanecerá inalterado até que use o comando <guimenuitem
>Gravar</guimenuitem
>. </para>
<para
>Se estiverem seleccionados vários ficheiros, só os valores que são idênticos em todos os ficheiros seleccionados é que são apresentados. Em todos os outros controlos, os valores vazio descritos acima são apresentados. Todas as opções de marcação estão desmarcadas para evitar modificações indesejadas. Se tiver de definir um valor para todos os ficheiros seleccionados, poderá ser editado e a opção de marcação terá de estar assinalada. Os valores serão configurados para todos os ficheiros seleccionados quando a selecção é modificada e poderá ser gravado com o comando <guimenuitem
>Gravar</guimenuitem
>. </para>
<para
>As opções de marcação também controlam a operação da maioria dos comandos que afectam as marcas, como a cópia, colagem e transferência entre as marcas 1 e 2. Para facilitar o uso com vários ficheiros, onde todas as opções de marcação estão desligadas, estes comandos comportam-se da mesma forma quando todas as opções estão assinaladas ou quando estão todas não-assinaladas. </para>
<para
><guibutton
>Da Marca 2</guibutton
>: Os campos da marca 1 são definidos a partir dos valores da marca 2. Se for seleccionado apenas um ficheiro, os controlos da &GUI; são preenchidos com os valores da marca 2. Se forem seleccionados vários ficheiros, as marcas dos ficheiros são configuradas directamente. </para>
<para
><guibutton
>Copiar</guibutton
>: A área de cópia fica preenchida com os valores da Marca 1. Só os valores assinalados serão usados nos campos Colar subsequentes. </para>
<para
><guibutton
>Colar</guibutton
>: Cola os valores da área de cópia para os controlos da &GUI;. </para>
<para
><guibutton
>Remover</guibutton
>: Isto irá configurar todos os controlos da &GUI; com os seus valores vazios, o que faz com que se removam todos os valores. O ficheiro gravado não irá ter a marca 1. </para>
</sect2>

<sect2 id="tag2">
<title
>Marca 2</title>

<para
>Os controlos da &GUI; funcionam da mesma forma que foi descrita para a secção da <guilabel
>Marca 1</guilabel
>, só que o tamanho dos textos não fica limitado. </para>
<para
>Para a marca 2 <guilabel
>Género</guilabel
>, também poderá usar os seus próprios nomes para além dos géneros apresentados na lista, bastando para tal escrever o nome no campo de texto. </para>
<para
>A marca 2 não só pode conter os mesmos valores que a marca 1, como o formato é composto de forma flexível a partir de vários pacotes que, por sua vez, são compostos por vários campos. A tabela da marca 2 mostra todos os pacotes que estão disponíveis no ficheiro seleccionado. </para>
<para
><guibutton
>Editar</guibutton
>: Isto irá abrir uma janela que permite a uma pessoa editar todos os campos do pacote seleccionado. Se estiverem seleccionados vários ficheiros, os campos editados serão aplicados a todos os ficheiros seleccionados que tiverem esse pacote. </para>
<para
><guibutton
>Adicionar</guibutton
>: Um pedido para seleccionar o tipo de pacote que irá aparecer, para que possa editar um pacote do tipo seleccionado e adicionado ao ficheiro. Isto funciona também para adicionar um pacote de dados aos vários ficheiros seleccionados. </para>
<para
><guibutton
>Apagar</guibutton
>: Remove o pacote seleccionado nos ficheiros seleccionados. </para>
<para
>A opção <guilabel
>Arraste as imagens do álbum para aqui</guilabel
> aparece se o ficheiro não tiver incorporada a imagem da capa. Poderá adicionar uma imagem por arrastamento a partir de um navegador ou gestor de ficheiros e será aqui apresentada. Os pacotes das imagens poderão ser editados ou adicionados se fizer duplo-click sobre este controlo. </para>

</sect2>

<sect2 id="tag3">
<title
>Marca 3</title>

<para
>Alguns ficheiros poderão ter mais que duas marcas, ficando assim uma terceira secção de marca visível. Os seguintes tipos de ficheiros poderão ter uma dessas secções <guilabel
>Marca 3</guilabel
>: </para>
<itemizedlist>
<listitem
><para
>Os ficheiros MP3 poderão ter uma marca ID3v1.1, uma marca ID3v2 (2.3.0 ou 2.4.0) e na terceira secção uma marca APE. Essas marcas APE são usadas para a informação do ganho de reprodução. Na secção <guilabel
>Marca 3</guilabel
>, esta informação fica visível e a marca APE poderá ser removida com o botão <guibutton
>Remover</guibutton
>. </para
></listitem>
<listitem
><para
>O bloco INFO do RIFF dos ficheiros WAV está disponível na secção <guilabel
>Marca 3</guilabel
> dado que a secção <guilabel
>Marca 1</guilabel
> está dedicada à marcas ID3v1.1 e trata das suas restrições. A secção <guilabel
>Marca 2</guilabel
> ainda é usada para as marcas ID3v2.4.0, que também são suportadas nos ficheiros WAR, mas os blocos INFO do RIFF parecem ser melhor suportados. </para
></listitem>
<listitem
><para
>Os ficheiros FLAC normalmente usam um comentário Vorbis para os seus meta-dados. Contudo, existem ficheiros FLAC que têm marcas ID3v1 e ID3v2, que poderão ser encontradas nas secções <guilabel
>Marca 1</guilabel
> e <guilabel
>Marca 3</guilabel
>. As marcas ID3 nos ficheiros FLAC só são suportadas na TagLib; como tal, o 'plugin' OggFlacMetadata tem de estar desactivado na página <guilabel
>Plugins</guilabel
> da <link linkend="configure-kid3"
>configuração</link
>. </para
></listitem>
</itemizedlist>
<para
>Os controlos da &GUI; funcionam da mesma forma que foi descrita para a secção da <guilabel
>Marca 2</guilabel
>. </para>

</sect2>

<!--begin manpage ignore-->
<sect2 id="frame-list">
<title
>Lista de Pacotes</title>

<para
>O &kid3; consegue editar a maioria dos pacotes para todos os tipos de ficheiros suportados. Alguns dos pacotes são acedidos através dos nomes unificados, para que possam ser trocados entre ficheiros com diferentes formatos. Os pacotes que não são unificados poderão ser acedidos como pacotes específicos do formato. </para>

<table id="table-frame-list">
  <title
>Associação dos Tipos de Pacotes Unificados aos Vários Formatos</title>
   <tgroup cols="7">
     <thead>
       <row
><entry
>Unificado</entry
>           <entry
>ID3v2.3</entry
> <entry
>ID3v2.4</entry
> <entry
>MP4</entry
>            <entry
>ASF</entry
>                        <entry
>Vorbis</entry
>                 <entry
>RIFF</entry
></row>
     </thead>
     <tbody>
       <row
><entry
>Título</entry
>             <entry
><literal
>TIT2</literal
></entry
>    <entry
><literal
>TIT2</literal
></entry
>    <entry
><literal
>©nam</literal
></entry
>           <entry
><literal
>Título</literal
></entry
>                      <entry
><literal
>TÍTULO</literal
></entry
>                  <entry
><literal
>INAM</literal
></entry
></row>
       <row
><entry
>Artista</entry
>            <entry
><literal
>TPE1</literal
></entry
>    <entry
><literal
>TPE1</literal
></entry
>    <entry
><literal
>©ART</literal
></entry
>           <entry
><literal
>Autor</literal
></entry
>                     <entry
><literal
>ARTIST</literal
></entry
>                 <entry
><literal
>IART</literal
></entry
></row>
       <row
><entry
>Álbum</entry
>             <entry
><literal
>TALB</literal
></entry
>    <entry
><literal
>TALB</literal
></entry
>    <entry
><literal
>©alb</literal
></entry
>           <entry
><literal
>WM/AlbumTitle</literal
></entry
>              <entry
><literal
>ALBUM</literal
></entry
>                  <entry
><literal
>IPRD</literal
></entry
></row>
       <row
><entry
>Comentário</entry
>           <entry
><literal
>COMM</literal
></entry
>    <entry
><literal
>COMM</literal
></entry
>    <entry
><literal
>©cmt</literal
></entry
>           <entry
><literal
>Descrição</literal
></entry
>                <entry
><literal
>COMMENT</literal
></entry
>                <entry
><literal
>ICMT</literal
></entry
></row>
       <row
><entry
>Data</entry
>              <entry
><literal
>TYER</literal
></entry
>    <entry
><literal
>TDRC</literal
></entry
>    <entry
><literal
>©day</literal
></entry
>           <entry
><literal
>WM/Year</literal
></entry
>                    <entry
><literal
>DATE</literal
></entry
>                   <entry
><literal
>ICRD</literal
></entry
></row>
       <row
><entry
>Número de Faixa</entry
>      <entry
><literal
>TRCK</literal
></entry
>    <entry
><literal
>TRCK</literal
></entry
>    <entry
><literal
>trkn</literal
></entry
>           <entry
><literal
>WM/TrackNumber</literal
></entry
>             <entry
><literal
>TRACKNUMBER</literal
></entry
>            <entry
><literal
>IPRT</literal
> ou <literal
>ITRK</literal
></entry
></row>
       <row
><entry
>Género</entry
>             <entry
><literal
>TCON</literal
></entry
>    <entry
><literal
>TCON</literal
></entry
>    <entry
><literal
>©gen</literal
></entry
>           <entry
><literal
>WM/Genre</literal
></entry
>                   <entry
><literal
>GENRE</literal
></entry
>                  <entry
><literal
>IGNR</literal
></entry
></row>
       <row
><entry
>Artista do Álbum</entry
>      <entry
><literal
>TPE2</literal
></entry
>    <entry
><literal
>TPE2</literal
></entry
>    <entry
><literal
>aART</literal
></entry
>           <entry
><literal
>WM/AlbumArtist</literal
></entry
>             <entry
><literal
>ALBUMARTIST</literal
></entry
>            <entry
></entry
></row>
       <row
><entry
>Arranger</entry
>          <entry
><literal
>IPLS</literal
></entry
>    <entry
><literal
>TIPL</literal
></entry
>    <entry
><literal
>ARRANGER</literal
></entry
>       <entry
><literal
>WM/Producer</literal
></entry
>                <entry
><literal
>ARRANGER</literal
></entry
>               <entry
><literal
>IENG</literal
></entry
></row>
       <row
><entry
>Autor</entry
>            <entry
><literal
>TOLY</literal
></entry
>    <entry
><literal
>TOLY</literal
></entry
>    <entry
><literal
>AUTOR</literal
></entry
>         <entry
></entry
>                                              <entry
><literal
>AUTOR</literal
></entry
>                 <entry
></entry
></row>
       <row
><entry
>BPM</entry
>               <entry
><literal
>TBPM</literal
></entry
>    <entry
><literal
>TBPM</literal
></entry
>    <entry
><literal
>tmpo</literal
></entry
>           <entry
><literal
>WM/BeatsPerMinute</literal
></entry
>          <entry
><literal
>BPM</literal
></entry
>                    <entry
><literal
>IBPM</literal
></entry
></row>
       <row
><entry
>Número do Catálogo</entry
>    <entry
><literal
>TXXX:CATALOGNUMBER</literal
></entry
> <entry
><literal
>TXXX:CATALOGNUMBER</literal
></entry
>                            <entry
></entry
> <entry
></entry
>                              <entry
><literal
>CATALOGNUMBER</literal
></entry
>          <entry
></entry
></row>
       <row
><entry
>Compilação</entry
>       <entry
><literal
>TCMP</literal
></entry
>    <entry
><literal
>TCMP</literal
></entry
>    <entry
><literal
>cpil</literal
></entry
>           <entry
></entry
>                                              <entry
><literal
>COMPILATION</literal
></entry
>            <entry
></entry
></row>
       <row
><entry
>Compositor</entry
>          <entry
><literal
>TCOM</literal
></entry
>    <entry
><literal
>TCOM</literal
></entry
>    <entry
><literal
>©wrt</literal
></entry
>           <entry
><literal
>WM/Composer</literal
></entry
>                <entry
><literal
>COMPOSER</literal
></entry
>               <entry
><literal
>IMUS</literal
></entry
></row>
       <row
><entry
>Condutor</entry
>         <entry
><literal
>TPE3</literal
></entry
>    <entry
><literal
>TPE3</literal
></entry
>    <entry
><literal
>CONDUCTOR</literal
></entry
>      <entry
><literal
>WM/Conductor</literal
></entry
>               <entry
><literal
>CONDUCTOR</literal
></entry
>              <entry
></entry
></row>
       <row
><entry
>Direitos de cópia</entry
>         <entry
><literal
>TCOP</literal
></entry
>    <entry
><literal
>TCOP</literal
></entry
>    <entry
><literal
>cprt</literal
></entry
>           <entry
><literal
>Direitos de cópia</literal
></entry
>                  <entry
><literal
>COPYRIGHT</literal
></entry
>              <entry
><literal
>ICOP</literal
></entry
></row>
       <row
><entry
>Descrição</entry
>       <entry
><literal
>TIT3</literal
></entry
>    <entry
><literal
>TIT3</literal
></entry
>    <entry
><literal
>desc</literal
></entry
>           <entry
><literal
>WM/SubTitleDescription</literal
></entry
>     <entry
><literal
>DESCRIÇÃO</literal
></entry
>            <entry
></entry
></row>
       <row
><entry
>Número do Disco</entry
>       <entry
><literal
>TPOS</literal
></entry
>    <entry
><literal
>TPOS</literal
></entry
>    <entry
><literal
>disco</literal
></entry
>           <entry
><literal
>WM/PartOfSet</literal
></entry
>               <entry
><literal
>DISCNUMBER</literal
></entry
>             <entry
></entry
></row>
       <row
><entry
>Encoded-by</entry
>        <entry
><literal
>TENC</literal
></entry
>    <entry
><literal
>TENC</literal
></entry
>    <entry
><literal
>©enc</literal
></entry
>           <entry
><literal
>WM/EncodedBy</literal
></entry
>               <entry
><literal
>ENCODED-BY</literal
></entry
>             <entry
><literal
>ITCH</literal
></entry
></row>
       <row
><entry
>Configuração do Codificador</entry
>  <entry
><literal
>TSSE</literal
></entry
>    <entry
><literal
>TSSE</literal
></entry
>    <entry
><literal
>©too</literal
></entry
>           <entry
><literal
>WM/EncodingSettings</literal
></entry
>        <entry
><literal
>ENCODERSETTINGS</literal
></entry
>        <entry
><literal
>ISFT</literal
></entry
></row>
       <row
><entry
>Hora da Codificação</entry
>     <entry
></entry
>                           <entry
><literal
>TDEN</literal
></entry
>    <entry
></entry
>                                  <entry
><literal
>WM/EncodingTime</literal
></entry
>            <entry
><literal
>ENCODINGTIME</literal
></entry
>           <entry
><literal
>IDIT</literal
></entry
></row>
       <row
><entry
>Agrupamento</entry
>          <entry
><literal
>GRP1</literal
></entry
>    <entry
><literal
>GRP1</literal
></entry
>    <entry
><literal
>©grp</literal
></entry
>           <entry
></entry
>                                              <entry
><literal
>GROUPING</literal
></entry
>               <entry
></entry
></row>
       <row
><entry
>Chave Inicial</entry
>       <entry
><literal
>TKEY</literal
></entry
>    <entry
><literal
>TKEY</literal
></entry
>    <entry
></entry
>                                  <entry
><literal
>WM/InitialKey</literal
></entry
>              <entry
><literal
>INITIALKEY</literal
></entry
>             <entry
></entry
></row>
       <row
><entry
>ISRC</entry
>              <entry
><literal
>TSRC</literal
></entry
>    <entry
><literal
>TSRC</literal
></entry
>    <entry
><literal
>ISRC</literal
></entry
>           <entry
><literal
>WM/ISRC</literal
></entry
>                    <entry
><literal
>ISRC</literal
></entry
>                   <entry
><literal
>ISRC</literal
></entry
></row>
       <row
><entry
>Língua</entry
>          <entry
><literal
>TLAN</literal
></entry
>    <entry
><literal
>TLAN</literal
></entry
>    <entry
><literal
>LANGUAGE</literal
></entry
>       <entry
><literal
>WM/Language</literal
></entry
>                <entry
><literal
>LANGUAGE</literal
></entry
>               <entry
><literal
>ILNG</literal
></entry
></row>
       <row
><entry
>Letrista</entry
>          <entry
><literal
>TEXT</literal
></entry
>    <entry
><literal
>TEXT</literal
></entry
>    <entry
><literal
>LYRICIST</literal
></entry
>       <entry
><literal
>WM/Writer</literal
></entry
>                  <entry
><literal
>LYRICIST</literal
></entry
>               <entry
><literal
>IWRI</literal
></entry
></row>
       <row
><entry
>Letras Musicais</entry
>            <entry
><literal
>USLT</literal
></entry
>    <entry
><literal
>USLT</literal
></entry
>    <entry
><literal
>©lyr</literal
></entry
>           <entry
><literal
>WM/Lyrics</literal
></entry
>                  <entry
><literal
>LYRICS</literal
></entry
>                 <entry
></entry
></row>
       <row
><entry
>Meio</entry
>             <entry
><literal
>TMED</literal
></entry
>    <entry
><literal
>TMED</literal
></entry
>    <entry
><literal
>SOURCEMEDIA</literal
></entry
>    <entry
></entry
>                                              <entry
><literal
>SOURCEMEDIA</literal
></entry
>            <entry
><literal
>IMED</literal
></entry
></row>
       <row
><entry
>Espírito</entry
>              <entry
></entry
>                           <entry
><literal
>TMOO</literal
></entry
>    <entry
></entry
>                                  <entry
><literal
>WM/Mood</literal
></entry
>                    <entry
><literal
>MOOD</literal
></entry
>                   <entry
></entry
></row>
       <row
><entry
>Álbum Original</entry
>    <entry
><literal
>TOAL</literal
></entry
>    <entry
><literal
>TOAL</literal
></entry
>    <entry
><literal
>ORIGINALALBUM</literal
></entry
>  <entry
><literal
>WM/OriginalAlbumTitle</literal
></entry
>      <entry
><literal
>ORIGINALALBUM</literal
></entry
>          <entry
></entry
></row>
       <row
><entry
>Artista Original</entry
>   <entry
><literal
>TOPE</literal
></entry
>    <entry
><literal
>TOPE</literal
></entry
>    <entry
><literal
>ORIGINALARTIST</literal
></entry
> <entry
><literal
>WM/OriginalArtist</literal
></entry
>          <entry
><literal
>ORIGINALARTIST</literal
></entry
>         <entry
></entry
></row>
       <row
><entry
>Data Original</entry
>     <entry
><literal
>TORY</literal
></entry
>    <entry
><literal
>TDOR</literal
></entry
>    <entry
><literal
>ORIGINALDATE</literal
></entry
>   <entry
><literal
>WM/OriginalReleaseYear</literal
></entry
>     <entry
><literal
>ORIGINALDATE</literal
></entry
>           <entry
></entry
></row>
       <row
><entry
>Artista</entry
>         <entry
><literal
>IPLS</literal
></entry
>    <entry
><literal
>TMCL</literal
></entry
>    <entry
><literal
>PERFORMER</literal
></entry
>      <entry
></entry
>                                              <entry
><literal
>PERFORMER</literal
></entry
>              <entry
><literal
>ISTR</literal
></entry
></row>
       <row
><entry
>Imagem</entry
>           <entry
><literal
>APIC</literal
></entry
>    <entry
><literal
>APIC</literal
></entry
>    <entry
><literal
>covr</literal
></entry
>           <entry
><literal
>WM/Picture</literal
></entry
>                 <entry
><literal
>METADATA_BLOCK_PICTURE</literal
></entry
> <entry
></entry
></row>
       <row
><entry
>Publicador</entry
>         <entry
><literal
>TPUB</literal
></entry
>    <entry
><literal
>TPUB</literal
></entry
>    <entry
><literal
>PUBLISHER</literal
></entry
>      <entry
><literal
>WM/Publisher</literal
></entry
>               <entry
><literal
>PUBLISHER</literal
></entry
>              <entry
><literal
>IPUB</literal
></entry
></row>
       <row
><entry
>Classificação</entry
>            <entry
><literal
>POPM</literal
></entry
>    <entry
><literal
>POPM</literal
></entry
>    <entry
><literal
>taxa</literal
></entry
>           <entry
><literal
>WM/SharedUserRating</literal
></entry
>        <entry
><literal
>RATING</literal
></entry
>                 <entry
><literal
>IRTD</literal
></entry
></row>
       <row
><entry
>País de Lançamento</entry
>   <entry
><literal
>TXXX:RELEASECOUNTRY</literal
></entry
> <entry
><literal
>TXXX:RELEASECOUNTRY</literal
></entry
>       <entry
></entry
>    <entry
></entry
>                                              <entry
><literal
>RELEASECOUNTRY</literal
></entry
>         <entry
><literal
>ICNT</literal
></entry
></row>
       <row
><entry
>Data de Lançamento</entry
>      <entry
></entry
>                           <entry
><literal
>TDRL</literal
></entry
>    <entry
><literal
>RELEASEDATE</literal
></entry
>    <entry
></entry
>                                              <entry
><literal
>RELEASEDATE</literal
></entry
>            <entry
></entry
></row>
       <row
><entry
>Mistura</entry
>           <entry
><literal
>TPE4</literal
></entry
>    <entry
><literal
>TPE4</literal
></entry
>    <entry
><literal
>REMIXER</literal
></entry
>        <entry
><literal
>WM/ModifiedBy</literal
></entry
>              <entry
><literal
>REMIXER</literal
></entry
>                <entry
><literal
>IEDT</literal
></entry
></row>
       <row
><entry
>Ordenar pelo Álbum</entry
>        <entry
><literal
>TSOA</literal
></entry
>    <entry
><literal
>TSOA</literal
></entry
>    <entry
><literal
>soal</literal
></entry
>           <entry
><literal
>WM/AlbumSortOrder</literal
></entry
>          <entry
><literal
>ALBUMSORT</literal
></entry
>              <entry
></entry
></row>
       <row
><entry
>Ordenar pelo Artista do Álbum</entry
> <entry
><literal
>TSO2</literal
></entry
>    <entry
><literal
>TSO2</literal
></entry
>    <entry
><literal
>soaa</literal
></entry
>           <entry
></entry
>                                              <entry
><literal
>ALBUMARTISTSORT</literal
></entry
>        <entry
></entry
></row>
       <row
><entry
>Ordenar pelo Artista</entry
>       <entry
><literal
>TSOP</literal
></entry
>    <entry
><literal
>TSOP</literal
></entry
>    <entry
><literal
>soar</literal
></entry
>           <entry
><literal
>WM/ArtistSortOrder</literal
></entry
>         <entry
><literal
>ARTISTSORT</literal
></entry
>             <entry
></entry
></row>
       <row
><entry
>Ordenar pelo Commpositor</entry
>     <entry
><literal
>TSOC</literal
></entry
>    <entry
><literal
>TSOC</literal
></entry
>    <entry
><literal
>soco</literal
></entry
>           <entry
></entry
>                                              <entry
><literal
>COMPOSERSORT</literal
></entry
>           <entry
></entry
></row>
       <row
><entry
>Nome da Ordenação</entry
>         <entry
><literal
>TSOT</literal
></entry
>    <entry
><literal
>TSOT</literal
></entry
>    <entry
><literal
>sonm</literal
></entry
>           <entry
><literal
>WM/TitleSortOrder</literal
></entry
>          <entry
><literal
>TITLESORT</literal
></entry
>              <entry
></entry
></row>
       <row
><entry
>Legenda</entry
>          <entry
></entry
>                           <entry
><literal
>TSST</literal
></entry
>    <entry
><literal
>SUBTITLE</literal
></entry
>       <entry
><literal
>WM/SubTitle</literal
></entry
>                <entry
><literal
>SUBTITLE</literal
></entry
>               <entry
><literal
>PRT1</literal
></entry
></row>
       <row
><entry
>Página Web</entry
>           <entry
><literal
>WOAR</literal
></entry
>    <entry
><literal
>WOAR</literal
></entry
>    <entry
><literal
>WEBSITE</literal
></entry
>        <entry
><literal
>WM/AuthorURL</literal
></entry
>               <entry
><literal
>WEBSITE</literal
></entry
>                <entry
><literal
>IBSU</literal
></entry
></row>
       <row
><entry
>Trabalho</entry
>              <entry
><literal
>TIT1</literal
></entry
>    <entry
><literal
>TIT1</literal
></entry
>    <entry
><literal
>©wrk</literal
></entry
>           <entry
><literal
>WM/ContentGroupDescription</literal
></entry
> <entry
><literal
>WORK</literal
></entry
>                   <entry
></entry
></row>
       <row
><entry
>Ficheiro de Áudio da WWW</entry
>    <entry
><literal
>WOAF</literal
></entry
>    <entry
><literal
>WOAF</literal
></entry
>    <entry
></entry
>                                  <entry
><literal
>WM/AudioFileURL</literal
></entry
>            <entry
><literal
>WWWAUDIOFILE</literal
></entry
>           <entry
></entry
></row>
       <row
><entry
>Fonte de Áudio da WWW</entry
>  <entry
><literal
>WOAS</literal
></entry
>    <entry
><literal
>WOAS</literal
></entry
>    <entry
></entry
>                                  <entry
><literal
>WM/AudioSourceURL</literal
></entry
>          <entry
><literal
>WWWAUDIOSOURCE</literal
></entry
>         <entry
></entry
></row>
     </tbody>
   </tgroup>
 </table>

<para
>Comentários referentes às associações aos nomes de pacotes unificados: <itemizedlist>
<listitem
><para
>O número de nomes de pacotes unificados é limitado com base no facto de que uma associação adequada deverá ser possível para todos os formatos de ficheiros suportados. A maioria das marcas suportam pacotes com nomes arbitrários; estes serão usados se não estiver disponível nenhum pacote específico (<abbrev
>p.ex.</abbrev
> os nomes em maiúsculas na coluna MP4). Se não existir essa possibilidade, alguns tipos de pacotes poderão não ser suportados para o formato, <abbrev
>p.ex.</abbrev
> o Autor e o Artista no ASF (WMA). </para
></listitem>
<listitem
><para
>As associações não são escolhidas de forma arbitrária; elas são vocacionadas para a utilização dos pacotes nas outras aplicações e dispositivos. Como tal, o pacote de ID3v2 "TPE2 - Banda/orquestra/acompanhamento" não sugere a sua utilização como Artista do Álbum, embora este seja usado frequentemente. O significado actual para o ID3v2, por outro lado, é a razão pela qual este pacote é usado para a orquestra na importação (<abbrev
>p.ex.</abbrev
> a partir do Discogs), ainda que isto possa parecer um pouco estranho para os outros formatos de marcas. </para
></listitem>
<listitem
><para
>As associações nem sempre são bijectivas. Como tal, o ID3v2.3 usa um pacote IPLS para o Maestro e Artista. Ao ler de volta, ambos os pacotes são apresentados como "Maestro". </para
></listitem>
<listitem
><para
>Os pacotes Maestro e Artista usam um formato específico para o conteúdo deles: "envolvimento 1|envolvido 1|envolvimento 2|envolvido 2|...", por exemplo "Maestro de Coro|Ernst Dunshirn|Voz Soprano|Anna Netrebko". Isto irá criar pacotes IPLS (ID3v2.3) ou TIPL/TMCL (ID3v2.4) com uma lista de textos no formato indicado (o "|" é usado como separador entre textos). Os valores neste formato são também configurados ao importar os dados a partir dos servidores que oferecem esta informação. </para
></listitem>
<listitem
><para
>Para usar de forma explícita um nome de pacote específico que entre em conflito com um nome de pacote unificado, anteceda-o com um ponto de exclamação. Por exemplo, se adicionar um pacote do tipo "<replaceable
>Meio</replaceable
>" num comentário do Vorbis, irá criar um pacote com o nome "<literal
>SOURCEMEDIA</literal
>" devido à associação de tipos unificada. Para adicionar um pacote com o nome "<literal
>MEIO</literal
>" e não "<literal
>SOURCEMEDIA</literal
>", use "<literal
>!MEIO</literal
>" para forçar o nome explícito. </para
></listitem>
</itemizedlist>
</para>

</sect2>
<!--end manpage ignore-->

<sect2 id="synchronized-lyrics">
<title
>Letras Sincronizadas e Códigos de Tempos Sincronizados</title>

<para
>Para ter a informação sincronizada com os dados de áudio, está disponível um editor específico. Estes pacotes têm suporte para as marcas ID3v2.3.0 e ID3v2.4.0. Para adicionar uma dessas marcas, o nome do pacote específico tem de ser seleccionado na lista que aparece quando carrega no botão <guibutton
>Adicionar</guibutton
> - <guilabel
>Letras Sincronizadas</guilabel
> ou <guilabel
>Códigos de Temporização de Eventos</guilabel
>, respectivamente. O editor é o mesmo para ambos os tipos; para os códigos de temporização de eventos, só está disponível um conjunto predefinido de eventos enquanto que, nas letras sincronizadas, terá de introduzir texto. No texto seguinte é explicada a edição de letras sincronizadas. </para>
<para
>Um ficheiro que tenha uma marca ID3v2 fica seleccionado, pelo que poderá entrar no editor de letras musicais se usar o botão <guibutton
>Adicionar</guibutton
> e seleccionar as <guilabel
>Letras Sincronizadas</guilabel
>. Para uma área de Letras Sincronizadas existente, ao seleccionar o mesmo poderá carregar no botão <guibutton
>Editar</guibutton
>. O leitor é automaticamente aberto com o ficheiro actual, para que possa reproduzir e pausar o ficheiro para sincronizar as letras musicais. </para>
<para
>A configuração no topo do editor do SYLT normalmente não tem de ser alterada. Se as letras tiverem caracteres que não estejam presentes no conjunto de caracteres Latin 1, a mudança da codificação de texto para UTF16 (ou UTF8 o caso do ID3v2.4.0) será aconselhada. Para as letras em Inglês e para o máximo de compatibilidade, deverá ser usado o ISO-8859-1. </para>
<para
>A secção das <guilabel
>Letras Musicais</guilabel
> tem cinco botões no topo. O <guibutton
>Adicionar</guibutton
> irá adicionar um novo evento de tempo na tabela. O tempo é retirado a partir da posição do leitor, adicionando assim um item enquanto reproduz a faixa irá adicionar uma linha para a posição reproduzida de momento. Os eventos na tabela têm de estar ordenados de forma cronológica, como tal a linha será inserida na posição adequada. Os itens com tempos inválidos são tratados de forma especial: Se a linha seleccionada de momento tiver um tempo inválido, a sua data/hora será substituída pelo tempo actual em vez de adicionar uma nova linha. Se o tempo actal não for inválido, a primeira linha com um tempo inválido será usada caso exista. Este comportamento deverá facilitar a adição de tempos se o texto das letras já estiver na tabela, mas estiverem a faltar os tempos (o que é o caso ao importar letras não sincronizadas). Lembre-se que o tempo inválido é representado como 00:00.00, <abbrev
>i.e.</abbrev
> o mesmo que o tempo no início absoluto da faixa, que não é inválido. Para invalidar um tempo, carregue na tecla <keycap
>Delete</keycap
> ou use a opção <guimenu
>Limpar</guimenu
> do menu de contexto. As novas linhas introduzidas com a opção <guimenu
>Inserir uma linha</guimenu
> do menu de contexto ou criadas quando importar as letras não sincronizadas com as opções <guibutton
>Da Área de Transferência</guibutton
> ou <guibutton
>Importar</guibutton
> também contêm tempos inválidos. As linhas na tabela poderão ser removidas se carregar no botão <guibutton
>Apagar</guibutton
> ou se usar a opção <guimenu
>Apagar as linhas</guimenu
> do menu de contexto. </para>
<para
>As letras sincronizadas poderão ser importadas a partir de um ficheiro com o botão <guibutton
>Importar</guibutton
>. O formato esperado é o LRC simples ou o avançado. Se o ficheiro seleccionado não tiver um parêntesis recto na primeira linha, é suposto ser um ficheiro de texto simples com letras não sincronizadas. As linhas desse ficheiro são então importadas com horas inválidas. A informação da data/hora poderá ser adicionada através do botão <guibutton
>Adicionar</guibutton
> ou introduzidas manualmente. Também é possível importar as letras se copiar-colar com a opção <guilabel
>Da Área de Transferência</guilabel
>. Poderá gravar as letras sincronizadas nos ficheiros LRC com a opção <guibutton
>Exportar</guibutton
>. Lembre-se que só os itens com tempos válidos serão exportados e que os itens serão ordenados por esses tempos. Os itens com tempos inválidos não serão guardados no editor de pacotes SYLT, por isso certifique-se que adiciona toda a informação de tempos antes de sair da janela. </para>
<para
>A <ulink url="http://id3.org/id3v2.4.0-frames"
>especificação do ID3</ulink
> sugere uma data/hora para cada sílaba. Contudo, a maioria dos leitores só suportam a granularidade de uma linha ou frase. Para suportar ambos os casos de uso, o &kid3; segue as mesmas convenções que o <ulink url="http://www.compuphase.com/software_sylteditor.htm"
>Editor do SYLT</ulink
>. O texto que é introduzido na tabela assume-se que inicia uma nova linha, a mesmo que comece por um espaço ou hífen. São possíveis excepções a esta regra se iniciar uma linha com um sublinhado ('_') para forçar a continuação ou um cardinal ('#') para forçar uma linha nova. Estes caracteres de escape não são guardados dentro do pacote SYLT. Dentro do mesmo pacote, as novas linhas começam com um carácter de mudança de linha (hex 0A), enquanto as continuações não. Ao ler os pacotes SYLT, o &kid3; verifica se o primeiro elemento começa com uma mudança de linha. Se este não for o caso, assume-se que todos os elementos são linhas novas e que não são usadas continuações de sílabas. </para>
<para
>Quando a faixa é reproduzida, a linha associada com a posição actual de reprodução fica realçada, para que a correcção da informação de sincronização possa ser validada. Se tiver de adicionar um deslocamento a uma ou mais datas/horas, podê-lo-´a fazer com o menu de contexto <guimenu
>Adicionar um deslocamento</guimenu
>. Poderá usar valores negativos para reduzir o tempo. Se usar o <guimenu
>Ir para a posição</guimenu
> no menu de contexto, é possível definir a posição de reprodução com a hora da linha seleccionada. </para>
<para>
<emphasis
>O procedimento recomendado é adicionar novas letras musicais sincronizadas</emphasis>
<itemizedlist>
<listitem
><para
>Obtenha as letras musicais não sincronizadas, <abbrev
>p.ex.</abbrev
> usando a opção <menuchoice
><guimenu
>Letras</guimenu
><guimenuitem
>Incorporar as Letras</guimenuitem
></menuchoice
> no menu de contexto da lista de ficheiros.</para
></listitem>
<listitem
><para
>Copie as letras não sincronizadas para a área de transferência, bastando para tal ir à linha <guilabel
>Letras</guilabel
> na tabela de pacotes e carregando em <keycombo
>&Ctrl;<keycap
>C</keycap
></keycombo
>.</para
></listitem>
<listitem
><para
>Adicione um pacote de letras sincronizadas (<guibutton
>Adicionar...</guibutton
>, <guilabel
>Letras Sincronizadas</guilabel
>, <guibutton
>OK</guibutton
>), carregando depois em <guibutton
>Da Área de Transferência</guibutton
>.</para
></listitem>
<listitem
><para
>Agora todas as linhas das letras musicais não sincronizadas estão na tabela, tendo todas as horas inválidas (0:0:0.00). Poderá apagar os elementos vazios antes de mais nada.</para
></listitem>
<listitem
><para
>Comece a tocar a música, carregando para tal no botão de reprodução <guibutton
>&#9658;</guibutton
> na barra de reprodução no fundo da janela principal.</para
></listitem>
<listitem
><para
>Quando chegar à linha seguinte de letras musicais com datas inválidas, carregue em <guibutton
>Adicionar</guibutton
> ou carregue em <keycombo
>&Alt;<keycap
>A</keycap
></keycombo
>, actualizando assim a data/hora.</para
></listitem>
<listitem
><para
>Continue desta forma até que todas as datas/horas estejam configuradas. Se lhe faltar algo, pare a reprodução e limpe as datas/horas com a tecla <keycap
>Delete</keycap
> ou seleccionando-as e usando a opção <guimenuitem
>Limpar</guimenuitem
> do menu de contexto. Para retomar a reprodução a partir de um determinado momento, use a opção <guimenuitem
>Mudar para a posição</guimenuitem
> do menu de contexto. </para
></listitem>
</itemizedlist>
</para>
</sect2>

</sect1>

<sect1 id="file-menu">
<title
>O Menu Ficheiro</title>
<para>
<variablelist>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>O</keycap
></keycombo
> </shortcut
> <guimenu
>Ficheiro</guimenu
> <guimenuitem
>Abrir...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Abre uma pasta.</action
> Todos os ficheiros que corresponderem ao filtro de nomes indicado serão apresentados na lista de ficheiros, ficando seleccionado o ficheiro pretendido.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Abrir um Recente</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Abre uma pasta aberta recentemente.</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>D</keycap
></keycombo
> </shortcut
> <guimenu
>Ficheiro</guimenu
> <guimenuitem
>Abrir uma Pasta...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Abre uma pasta.</action
> Todos os ficheiros que corresponderem ao filtro de nomes indicado serão apresentados na lista de ficheiros.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycap
>F5</keycap
> </shortcut
> <guimenu
>Ficheiro</guimenu
> <guimenuitem
>Recarregar</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Actualiza o conteúdo da pasta.</action
> Os ficheiros modificados têm de ser gravados antes. As sub-pastas expandidas serão fechadas.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>S</keycap
></keycombo
> </shortcut
> <guimenu
>Ficheiro</guimenu
> <guimenuitem
>Gravar</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Grava todos os ficheiros alterados na pasta.</action
> Os ficheiros alterados são marcados com um símbolo de disco na lista de ficheiros. Se algum dos nomes dos ficheiros tiver sido modificado, estes ficheiros irão mudar de nome.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Reverter</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Reverte as alterações de um ou mais ficheiros.</action
> Se não estiverem ficheiros seleccionados na lista, as modificações de todos os ficheiros serão revertidas, caso contrário só serão revertidas as modificações dos ficheiros seleccionados. </para
></listitem>
</varlistentry>

<varlistentry id="import">
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>A <action
>janela de Importação</action
> pode ser usada para importar os dados directamente de um servidor do freedb.org server, de um servidor do MusicBrainz, do Discogs, da Amazon ou de outras fontes de listas de faixas de álbuns num formato de texto. </para>
<para id="import-freedb"
>A importação de um servidor do freedb.org é possível se usar a janela que aparece quando selecciona a opção <guibutton
>Do Servidor:</guibutton
> <guibutton
>gnudb.org</guibutton
>. O nome do artista ou do álbum a procurar pode ser introduzido nos dois campos do topo, sendo apresentados os álbuns que correspondam à pesquisa quando carregar em <guibutton
>Procurar</guibutton
> e depois de receber os resultados do <ulink url="http://www.gnudb.org"
>www.gnudb.org</ulink
>. A importação dos dados da faixa de álbum é feita ao fazer duplo-click sobre o álbum na lista. O servidor de freedb.org a importar poderá ser seleccionado, assim como a localização do CGI. Os dados importados são apresentados na tabela de antevisão da janela de importação. Quando estiver satisfeito com as faixas apresentadas, as mesmas podem ser importadas se terminar a janela de importação com o <guibutton
>OK</guibutton
>. </para>
<para id="import-discogs"
>Poderá efectuar uma pesquisa no servidor do Discogs com a opção <guibutton
>Discogs</guibutton
>. Como na janela do <guibutton
>gnudb.org</guibutton
>, poderá introduzir o artista e o álbum, escolhendo depois dentro de uma lista de lançamentos.Poderá introduzir um <guilabel
>Código</guilabel
> para usar a API RESTful do Discogs em vez de usar a interface Web deles, a qual muda com frequência, comprometendo assim o processamento da importação. Terá de criar uma conta no <ulink url="https://www.discogs.com/"
>Discogs</ulink
> e depois gerar um código na página Web deles ("Settings/Developers, Generate new token" (Configuração/Programadores, Gerar um novo código)). Não se esqueça de <guibutton
>Gravar a Configuração</guibutton
> depois de introduzir o código para o usar também nos pedidos subsequentes. Se as <guilabel
>Marcas-Padrão</guilabel
> estiverem assinaladas, é importada a informação-padrão, <abbrev
>p.ex.</abbrev
> artista, álbum e título. Se estiverem assinaladas as <guilabel
>Marcas Adicionais</guilabel
>, poderá importar mais informações se estiverem disponíveis, <abbrev
>p.ex.</abbrev
> artistas, maestros ou o publicador. Se as <guilabel
>Imagens das Capas</guilabel
> estiver assinalada, será transferida a imagem da capa, se estiver disponível. </para>
<para id="import-amazon"
>Poderá efectuar uma pesquisa na Amazon com a opção <guibutton
>Amazon</guibutton
>. Tal como na janela do <guibutton
>gnudb.org</guibutton
>, poderá introduzir o artista e o álbum, escolhendo depois a partir de uma lista de lançamentos. Se as <guilabel
>Marcas Adicionais</guilabel
> estiverem marcadas, poderá importar mais informação desde que esteja disponível, <abbrev
>p.ex.</abbrev
> cantores, maestros ou publicadores. Se as <guilabel
>Imagens da Capa</guilabel
> estiver assinalada, será transferida a imagem da capa caso esteja disponível. </para>
<para id="import-musicbrainzrelease"
>Poderá pesquisar da mesma forma na base de dados de lançamentos do MusicBrainz, usando a opção <guibutton
>Da Versão do MusicBrainz</guibutton
>. O procedimento é o mesmo que está descrito em <guibutton
>Do gnudb.org</guibutton
>. </para>
<para id="import-musicbrainz"
>A importação de um servidor do MusicBrainz é possível se usar a janela que aparece quando seleccionar a opção <guibutton
>Da Impressão Digital do MusicBrainz</guibutton
>. Poderá seleccionar o Servidor como na janela de importação do freedb. Em baixo encontra-se uma tabela que apresenta os dados das faixas importadas. A coluna da direita mostra o estado da pesquisa no MusicBrainz, a qual começa como "Pendente" quando a janela é aberta. Depois é pesquisada a impressão digital e, se não devolver resultados, será testada outra pesquisa com as marcas no ficheiro. Como tal, pode ser útil para uma pesquisa com sucesso no MusicBrainz guardar a informação conhecida (<abbrev
>p.ex.</abbrev
> artista e álbum) nas marcas antes da importação. Se for encontrado um resultado, a pesquisa termina no estado "Reconhecida"; caso contrário, se não tiver sido encontrado nada ou se forem devolvidos resultados ambíguos, terá de ser seleccionado um deles pelo utilizador. O <guibutton
>OK</guibutton
> e o <guibutton
>Aplicar</guibutton
> usam os dados importados, enquanto o <guibutton
>Cancelar</guibutton
> fecha a janela. O fecho poderá demorar algum tempo, dado que todo o processo do MusicBrainz terá de ser encerrado. </para>

<para id="import-text"
>Para a importação de dados textuais, a opção <guibutton
>Do Ficheiro/Área de Transferência</guibutton
> abre uma sub-janela, onde estão disponíveis vários formatos de importação pré-configurados. Os dois primeiros, "CSV sem aspas" e "CSV com aspas", podem ser usados para importar dados que tenham sido exportados na janela de Exportação. Os dados em CSV podem ser editados numa folha de cálculo e devem ser gravados com tabulações como separadores. A importação deverá ser possível com o "CSV com aspas", que é mais flexível que a versão "CSV sem aspas". Contudo, os seus campos não podem ter aspas no conteúdo. Se só exportar do &kid3; e importar mais tarde, o "CSV sem aspas" pode ser usado como um formato simples para esse fim. Lembre-se que também existem as opções  "Exportar o CSV" e "Importar o CSV" no menu de contexto da lista de ficheiros, que usam programas para exportar e importar os dados em CSV de uma forma mais completa, poderosa e flexível. </para>

<para
>O próximo formato, "texto &HTML; do freedb", pode ser usado para copiar informações de uma página &HTML; do <ulink url="http://freedb.org"
>freedb.org</ulink
>. Pesquise um álbum no freedb e, se a informação desejada aparecer no navegador Web, copie o conteúdo para a área de transferência. Depois carregue no botão <guibutton
>Da Área de Transferência</guibutton
> para que as faixas importadas apareçam na tabela de antevisão no topo da janela. Se estiver satisfeito com os dados importados, termine a janela com o botão <guibutton
>OK</guibutton
>, que irá inserir os dados nas marcas da pasta actual. O destino (<guilabel
>Marca 1</guilabel
>, <guilabel
>Marca 2</guilabel
> ou <guilabel
>Marca 1 e Marca 2</guilabel
>) pode ser seleccionado numa lista. Os ficheiros na pasta actual deverão estar na ordem de faixas correctamente para ter as suas marcas atribuídas. Este é o caso caso elas estejam numeradas. </para>
<para
>O próximo formato de importação pré-configurado, o "código &HTML; do freedb", poderá ser usado se os dados estiverem disponíveis como um documento em &HTML;. A importação é possível com o botão <guibutton
>Do Ficheiro</guibutton
>, que abre um selector de ficheiros, ou copiando o seu conteúdo a partir de um editor e depois importando-o a partir da área de transferência. Este formato pode ser útil para a importação 'offline', ainda que o documento &HTML; possa também ser aberto num navegador e depois ser importado no primeiro formato através da área de transferência. </para>
<para
>Estão disponíveis mais formatos pré-configurados, <abbrev
>p.ex.</abbrev
> "Tempo do Título da Faixa". Poderá criar um formato personalizado vazio com o botão <guibutton
>Adicionar</guibutton
> para ser definido pelo utilizador. As duas linhas abaixo do nome do formato podem ser configuradas com uma expressão regular para capturar os campos a partir do texto a importar. A primeira expressão regular será processada uma vez por cada documento para reunir os dados de cada álbum, como o artista, o álbum, o ano e o género. A segunda linha é testada para corresponder a partir do início do documento até ao fim para obter os dados da faixa, normalmente o número e o título. As expressões regulares incluem todas as funcionalidades oferecidas pelo &Qt;, que correspondem à maior parte do que o Perl oferece. As construções com parêntesis "(..)" criam áreas de captura para os campos a importar e são antecedidas de códigos específicos do &kid3; para indicar qual o campo a capturar. Os códigos são os mesmos que são usados no formato dos nomes dos ficheiros, para além dos códigos apresentados abaixo; é possível qualquer nome de pacote: </para>

<para id="format-codes">
<itemizedlist>
<listitem
><para
>%s %{title} Título (Música)</para
></listitem>
<listitem
><para
>%a %{artist} Artista</para
></listitem>
<listitem
><para
>%l %{album} Álbum</para
></listitem>
<listitem
><para
>%c %{comment} Comentário</para
></listitem>
<listitem
><para
>%y %{year} Ano</para
></listitem>
<listitem
><para
>%t %{track} Faixa</para
></listitem>
<listitem
><para
>%g %{genre} Género</para
></listitem>
<listitem
><para
>%d %{duration} Duração</para
></listitem>
</itemizedlist>
</para>

<para
>Por exemplo, a expressão regular de uma faixa (segunda linha) para importar a partir de uma lista de reprodução .m3u poderia ser "<literal
>%{track}(\d+)\s+%{title}(\S[^\r\n]*)\.mp3[\r\n]</literal
>". Todos os formatos podem ser alterados se editar as expressões regulares e o nome, carregando depois em <guibutton
>Gravar a Configuração</guibutton
>. Elas ficarão guardadas no ficheiro <filename
>kid3rc</filename
> na pasta de configuração. Este ficheiro poderá ser editado directamente para ter mais formatos de importação ou poderá ser apagado para voltar aos formatos predefinidos. Os formatos podem ser apagados com <guibutton
>Remover</guibutton
>. </para>
<para
>A <guibutton
>Precisão</guibutton
> mostra uma estimativa de quão boa é a informação importada ao corresponder às faixas indicadas. Ele usa as durações das faixas ou os nomes dos ficheiros para calcular o nível de semelhança em percentagem. A <guilabel
>Imagem da Capa</guilabel
> mostra o &URL; da imagem da capa do álbum que será transferida. </para>
<para
>Para verificar se as faixas importadas correspondem ao conjunto actual de ficheiros, a duração das faixas importadas poderá ser comparada com a duração dos ficheiros. Esta funcionalidade poderá ser activada com a opção <guibutton
>Verificar a diferença máxima de tempo permitida (s):</guibutton
> para definir esse valor máximo de tolerância em segundos. Se ocorrer uma discrepância de valores, a duração aparece com um fundo vermelho na tabela de antevisão. </para>
<para
>Se os ficheiros estiverem ordenados de forma diferente das faixas importadas, as suas faixas atribuídas terão de ser alteradas. Esta tarefa poderá ser simplificada se usar os botões para <guilabel
>Corresponder a</guilabel
> <guibutton
>Duração</guibutton
>, <guibutton
>Faixa</guibutton
> e <guibutton
>Título</guibutton
>, os quais irão reordenar as faixas de acordo com o campo correspondente. Para corrigir manualmente as atribuições, poderá arrastar uma faixa com o botão <mousebutton
>esquerdo</mousebutton
> do rato e a tecla &Ctrl; carregada, sendo depois largada na nova posição. </para>
<para
>Quando a janela de importação estiver aberta, ela possui o conteúdo actual das marcas. O tipo de marca (Marca 1, Marca 2, Marca 1 e Marca 2) poderá ser seleccionado com a lista <guilabel
>Destino</guilabel
>. O botão à direita desta lista poderá ser usado para reverter a tabela ao conteúdo actual das marcas. As opções de marcação na primeira coluna da tabela poderão ser usadas para seleccionar as faixas que serão importadas. Isto pode ser útil se uma pasta possuir as faixas de ambos os &CD;'s de um &CD; duplo e só necessitar de importar as faixas do segundo &CD;. </para>
<para
>Para identificar as faixas que são importadas, é possível mostrar os nomes dos ficheiros ou as localizações completas dos mesmos, usando o menu de contexto do cabeçalho da tabela. Os valores na tabela de importação poderão ser editados. O botão de reverão à direita da lista <guilabel
>Destino</guilabel
> poderá ser usado para repor o conteúdo das marcas, o que também poderá ser útil depois de alterar o <guilabel
>Destino</guilabel
>. </para>
<para
>Quase todas as janelas possuem um botão <guibutton
>Gravar a Configuração</guibutton
>, que pode ser usado para guardar as definições específicas da janela, bem como o seu tamanho, de forma persistente. </para>

<para id="import-tags"
>A opção <guibutton
>Das Marcas</guibutton
> conduz a uma sub-janela para configurar os pacotes das marcas a partir do conteúdo de outros pacotes de marcas. Isto pode ser usado para simplificar a cópia de informação entre marcas ou para extrair uma parte de um pacote e inseri-la noutro. </para>
<para
>Tal como na janela para <link linkend="import-text"
>importar a partir de um ficheiro/área de transferência</link
>, existem formatos configuráveis à vontade para efectuar diferentes operações. Já existem alguns formatos pré-configurados para copiar o valor do Álbum para o Artista, Compositor ou Condutor do Álbum, assim como para extrair o número da faixa dos campos de Título que incluam um número. Existe também um formato para extrair um Sub-Título a partir de um campo de Título. </para>
<para
>O seguinte exemplo explica como adicionar um formato personalizado, o qual define a informação a partir do campo de Sub-Título também no campo de Comentário. Crie um novo formato com a opção <guibutton
>Adicionar</guibutton
> e indique um novo nome, <abbrev
>p.ex.</abbrev
> "<userinput
>Sub-título para Comentário</userinput
>". Depois indique "<userinput
>%{subtitle}</userinput
>" na <guilabel
>Origem</guilabel
> e "<userinput
>%{comment}(.*)</userinput
>" na <guilabel
>Extracção</guilabel
>, carregando finalmente em <guibutton
>Gravar a Configuração</guibutton
>. </para>
<para
>A expressão na <guilabel
>Origem</guilabel
> poderá conter os <link linkend="format-codes"
>códigos de formato</link
> para os pacotes de marcas arbitrários, podendo usar vários códigos para combinar o conteúdo dos diferentes pacotes. Para cada faixa, é gerado um texto a partir das suas marcas com o formato da <guilabel
>Origem</guilabel
> e a expressão regular da <guilabel
>Extracção</guilabel
> é aplicada a este texto para definir valores novos para as marcas. Os códigos dos formato são usados antes dos parêntesis de captura para indicar o pacote de marcas onde será guardado o texto capturado. Funciona da mesma forma que na <link linkend="import-text"
>importação de ficheiros/área de transferência</link
>. </para>
<para
>A opção <guimenuitem
>Importar a Partir das Marcas...</guimenuitem
> também está directamente disponível a partir do menu <guimenu
>Ficheiro</guimenu
>. A diferença entre estas duas funções é que a sub-janela de importação funciona sobre todos os ficheiros da pasta actual, enquanto a função do menu se aplica sobre os ficheiros seleccionados (que poderão estar em diferentes pastas). A função do menu suporta um código adicional "<userinput
>%{__return}</userinput
>" para devolver o valor extraído, o que poderá ser útil com as interfaces CLI e QML. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar do gnudb.org...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Importa a partir de um servidor do freedb.org, usando a pesquisa de álbuns do gnudb.org.</action
> Este item de menu abre a mesma janela de importação que o <guimenuitem
>Importar...</guimenuitem
>, mas abre directamente a janela do <guibutton
>gnudb.org</guibutton
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar do Discogs...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Importa a partir do servidor do Discogs.</action
> Este item de menu abre a mesma janela de importação que o <guimenuitem
>Importar...</guimenuitem
>, mas abre directamente a janela do <guibutton
>Discogs</guibutton
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar da Amazon...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Importa a partir da Amazon.</action
> Este item de menu abre a mesma janela de importação que o <guimenuitem
>Importar...</guimenuitem
>, mas abre directamente a janela da <guibutton
>Amazon</guibutton
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar da Versão do MusicBrainz...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Importa a partir do serviço de lançamentos do MusicBrainz.</action
> Este item de menu abre a mesma janela de importação que o <guimenuitem
>Importar...</guimenuitem
>, mas abre directamente a janela da <guibutton
>MusicBrainz</guibutton
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar da Impressão Digital do MusicBrainz...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Importa a partir de um servidor do MusicBrainz.</action
> Este item de menu abre a mesma janela de importação que o <guimenuitem
>Importar...</guimenuitem
>, mas abre directamente a janela de <guibutton
>Impressões Digitais do MusicBrainz</guibutton
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importar das Marcas...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Como o <link linkend="import-tags"
>Das Marcas</link
>, mas a importação é aplicada aos ficheiros seleccionados.</para
></listitem>
</varlistentry>

<varlistentry id="batch-import">
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Importação Automática...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>A <action
>Importação Automática</action
> permite a uma pessoa importar informações para vários álbuns a partir de vários serviços na Web. Se forem seleccionadas pastas na lista de ficheiros, serão importados os dados das faixas para as pastas seleccionadas. Se não for seleccionada nenhuma pasta, todas as pastas na lista de ficheiros serão importadas. </para>
<para
>O tipo de marca (Marca 1, Marca 2, Marca 1 e Marca 2) podem ser seleccionados com a lista <guilabel
>Destino</guilabel
>. </para>
<para
>Os perfis determinam quais os servidores que serão contactados para obter a informação do álbum. Alguns dos perfis são predefinidos (Tudo, MusicBrainz, Discogs, Imagens de Capas), sendo que poderá adicionar perfis personalizados com o botão <guibutton
>Adicionar</guibutton
> à direita da lista do <guilabel
>Perfil</guilabel
>. </para>
<para
>A tabela abaixo mostra os servidores que serão usados quando importar os dados dos álbuns com o perfil seleccionado. O processo de importação de um álbum termina se toda a informação necessária for encontrada, pelo que a ordem das linhas na tabela é importante. Poderá ser alterada com os botões <guibutton
>Subir</guibutton
> e <guibutton
>Descer</guibutton
>. O <guibutton
>Editar</guibutton
> pode ser usado para modificar um item existente. A selecção do <guibutton
>Servidor</guibutton
> oferece os mesmos servidores que podem ser usados nas funções de importação. As <guilabel
>Marcas-Padrão</guilabel
>, as <guilabel
>Marcas Adicionais</guilabel
> e as <guilabel
>Imagens das Capas</guilabel
> determinam a informação que será obtida a partir do servidor. Finalmente, a  <guilabel
>Precisão</guilabel
> é a granularidade mínima que deverá ser obtida para aceitar os dados importados. Se a precisão for insuficiente, será usado o próximo servidor na lista. A mesma janela que contém as propriedades do servidor aparece quando carregar em <guibutton
>Adicionar</guibutton
> para adicionar um novo item de servidor. Os itens existentes poderão ser removidos com o botão <guibutton
>Remover</guibutton
>. </para>
<para
>Para invocar uma importação automática em lote com o perfil seleccionado, carregue em <guibutton
>Iniciar</guibutton
>. Os detalhes sobre a importação em curso são apresentados no topo da janela. O processo poderá ser interrompido com o botão <guibutton
>Interromper</guibutton
>. </para>
 </listitem>
</varlistentry>

<varlistentry id="browse_pictures">
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Escolher as Imagens de Capas...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>A janela para <action
>Escolher as Imagens das Capas</action
> ajuda a descobrir as imagens das capas dos álbuns. O <guilabel
>Artista/Álbum</guilabel
> é preenchido a partir das marcas, se tal for possível. A <guilabel
>Origem</guilabel
> oferece uma variedade de páginas Web com imagens das capas dos álbuns. O &URL; com o artista e o álbum como parâmetros poderá ser consultado por baixo do nome. Poderá inserir valores codificados como &URL;'s para o artista se usar o "<userinput
>%u{artist}</userinput
>" e "<userinput
>%u{album}</userinput
>"; também são possíveis os outros valores a partir das marcas, tal como descrito em <link linkend="configure-kid3"
>Configurar o &kid3;</link
>, <guilabel
>Acções do Utilizador</guilabel
>. Poderá introduzir mais fontes a seguir ao elemento "Origem Personalizada", substituindo a "Origem Personalizada" pelo nome da fonte e carregar em Enter, introduzindo depois o &URL; e carregando finalmente em <guibutton
>Gravar a Configuração</guibutton
>. O comando do navegador resultante aparece no topo da janela e pode ser iniciado se carregar em <guibutton
>Escolher</guibutton
>. O navegador, que pode ser definido na configuração, é iniciado com a origem seleccionada. Poderá então arrastar uma imagem de capa a partir do navegador para a janela do &kid3;, para que a mesma fique configurada no pacote de imagem dos ficheiros seleccionados. </para>
<para
>Dado que nem todos os navegadores suportam o arrastamento de imagens e as imagens das páginas Web normalmente têm um &URL;, nesses casos o  &kid3; irá receber o &URL; e não a imagem. Se o &URL; apontar para uma imagem, a mesma será transferida. Contudo, se o &URL; fizer referência a outro recurso qualquer da Web, terá de ser traduzido para a imagem correspondente. Essas associações estão definidas na tabela de <guilabel
>extracção do &URL;</guilabel
>. A coluna da esquerda <guilabel
>Corresponder</guilabel
> contém uma expressão regular que é comparada com o &URL;. Se corresponder, as expressões capturadas entre parêntesis são introduzidas no padrão da coluna <guilabel
>&URL; da Imagem</guilabel
> à direita (nas posições marcadas com o \1 &etc;). A expressão regular substituída contém o &URL; da imagem. Com este mecanismo, as imagens das capas poderão ser importadas a partir da Amazon, Google Images, &etc; por arrastamento. Também é possível definir as suas próprias associações. </para>
</listitem>
</varlistentry>

<varlistentry id="export">
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Exportar...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>A <action
>Janela de Exportação</action
> é usada para guardar os dados das marcas num ficheiro ou na área de transferência. O editor no topo mostra uma antevisão dos dados a exportar. Se os dados da exportação tiverem tabulações, a exportação será apresentada numa tabela. Os dados serão gerados a partir das marcas na pasta actual, de acordo com o formato configurado. </para>
<para
>A configuração do formato é semelhante à da janela de Importação: O campo no topo contém o título (<abbrev
>p.ex.</abbrev
> "CSV sem aspas"), seguido do cabeçalho que será gerado no início do ficheiro. Os dados da faixa vêm a seguir; é usado para cada faixa. Finalmente, o rodapé pode ser usado para gerar algum texto final. </para>
<para
>Os campos de formato não contêm expressões regulares como na janela de Importação, mas apenas as expressões do formato de saída com expressões-% especiais, as quais serão substituídas pelos valores das marcas. O processo inteiro funciona como no formato dos nomes dos ficheiros, sendo usados os mesmos códigos para além de alguns códigos adicionais. Não só os códigos apresentados abaixo mas todos os nomes de pacotes de marcas poderão ser usados. </para>

<itemizedlist>
<listitem
><para
>%s %{title} Título (Música)</para
></listitem>
<listitem
><para
>%a %{artist} Artista</para
></listitem>
<listitem
><para
>%l %{album} Álbum</para
></listitem>
<listitem
><para
>%c %{comment} Comentário</para
></listitem>
<listitem
><para
>%y %{year} Ano</para
></listitem>
<listitem
><para
>%t %{track} Faixa (<abbrev
>p.ex.</abbrev
> 01)</para
></listitem>
<listitem
><para
>%t %{track.n} Faixa com o tamanho do campo 'n' (<abbrev
>p.ex.</abbrev
> 001 para %{track.3})</para
></listitem>
<listitem
><para
>%T %{tracknumber} Faixa (sem os zeros iniciais, <abbrev
>p.ex.</abbrev
> 1)</para
></listitem>
<listitem
><para
>%g %{genre} Género</para
></listitem>
<listitem
><para
>%f %{file} Nome do ficheiro</para
></listitem>
<listitem
><para
>%p %{filepath} Localização</para
></listitem>
<listitem
><para
>%{modificationdate} Data de modificação</para
></listitem>
<listitem
><para
>%{creationdate} Data de criação</para
></listitem>
<listitem
><para
>%u %{url} &URL;</para
></listitem>
<listitem
><para
>%{dirname} Nome da pasta</para
></listitem>
<listitem
><para
>%d %{duration} Duração em minutos:segundos</para
></listitem>
<listitem
><para
>%D %{seconds} Duração em segundos</para
></listitem>
<listitem
><para
>%n %{tracks} Número de faixas do álbum</para
></listitem>
<listitem
><para
>%e %{extension} Extensão do ficheiro</para
></listitem>
<listitem
><para
>%O %{tag1} O formato da marca 1 (ID3v1.1 ou vazio se inexistente)</para
></listitem>
<listitem
><para
>%o %{tag2} O formato da marca 2 (ID3v2.3.0, ID3v2.4.0, ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF ou vazio se inexistente)</para
></listitem>
<listitem
><para
>%b %{bitrate} Taxa de dados em kbit/s</para
></listitem>
<listitem
><para
>%v %{vbr} VBR ou vazio (apenas para o ID3v2.3 com a id3lib)</para
></listitem>
<listitem
><para
>%r %{samplerate} Taxa de amostragem em Hz</para
></listitem>
<listitem
><para
>%m %{mode} Modo do canal (Estéreo ou Estéreo Conjunto)</para
></listitem>
<listitem
><para
>%h %{channels} Número de canais (1 ou 2)</para
></listitem>
<listitem
><para
>%k %{codec} Codificador (<abbrev
>p.ex.</abbrev
> MPEG 1 Nível 3, MP4, Ogg Vorbis, FLAC, MPC, APE, ASF, AIFF, WAV)</para
></listitem>
</itemizedlist>

<para
>Existem alguns formatos predefinidos. O "CSV sem aspas" separa os campos com tabulações. Os dados neste formato poderão ser importados de novo para o &kid3;, usando o formato de importação com o mesmo nome. O "CSV com aspas" delimita adicionalmente os campos com aspas, o que facilita a importação para as folhas de cálculo. Contudo, os campos não poderão ter eles próprios aspas quando usar este formato. O "M3U Estendido" e o "PLS Estendido" geram listas de reprodução com atributos estendidos e com nomes de locais absolutos. O "HTML" pode ser usado para gerar uma página &HTML; com hiperligações para as faixas. O "Kover &XML;" cria um ficheiro que poderá ser importado pelo programa de impressão de capas Kover. Os "Detalhes Técnicos" oferecem informações sobre a taxa de dados, taxa de amostragem, canais, &etc; Finalmente, o "Formato Personalizado" é deixado em branco para a definição de um formato personalizado. Poderá definir mais formatos seus se adicionar linhas no ficheiro , <filename
>kid3rc</filename
> na pasta de configuração. Os outros formatos poderão ser adaptados de acordo com as suas necessidades. </para>
<para
>A <guilabel
>Origem</guilabel
> das marcas para gerar os dados de exportação (<guilabel
>Marca 1</guilabel
> ou <guilabel
>Marca 2</guilabel
>) poderá ser seleccionada com uma lista. Se carregar em <guibutton
>Para um Ficheiro</guibutton
> ou <guibutton
>Para a Área de Transferência</guibutton
>, irá guardar os dados nesses destinos. Os botões <guibutton
>OK</guibutton
> e <guibutton
>Cancelar</guibutton
> fecham a janela, sendo que o <guibutton
>OK</guibutton
> aceita as definições da janela actual. </para
></listitem>
</varlistentry>

<varlistentry id="create-playlist">
<term
><menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Criar uma Lista de Reprodução...</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Cria uma lista de reprodução.</action
> O formato e conteúdo da lista de reprodução poderão ser definidos com várias opções.</para>
<para
>O nome da lista de reprodução poderá ser o <guibutton
>Mesmo que o nome da pasta</guibutton
> ou usar um <guibutton
>Formato</guibutton
> com valores das marcas, <abbrev
>p.ex.</abbrev
> "<userinput
>%{artist} - %{album}</userinput
>" para ter o nome do artista e do álbum no nome do ficheiro da lista de reprodução. Os códigos do formato são os mesmos que em <link linkend="export"
>Exportar</link
>. A opção <guibutton
>Criar uma nova lista de reprodução vazia</guibutton
> irá criar uma lista de reprodução vazia com o nome indicado. A extensão depende do formato da lista de reprodução. </para>
<para
>A localização da lista de reprodução gerada é determinada pela selecção da lista <guilabel
>Criar em</guilabel
>. <variablelist>
<varlistentry
><term
>Pasta actual</term>
<listitem
><para
>A lista de reprodução é criada na pasta actual e só contém os ficheiros da pasta actual. A pasta actual é a pasta onde se encontra o ficheiro actual. Se estiverem seleccionados vários ficheiros, o ficheiro actual será provavelmente o último ficheiro seleccionado.</para
></listitem
></varlistentry>
<varlistentry
><term
>Todas as pastas</term>
<listitem
><para
>Uma lista de reprodução é criada em todas as pastas que contêm os ficheiros listados, sendo que cada lista contém os ficheiros dessa pasta. </para
></listitem
></varlistentry>
<varlistentry
><term
>Pasta de topo</term>
<listitem
><para
>Só é criada uma lista de reprodução na pasta de topo (<abbrev
>i.e.</abbrev
>, a pasta da lista de ficheiros) e contém os ficheiros listados na pasta de topo e em todas as suas sub-pastas. </para
></listitem
></varlistentry>
</variablelist>
</para>
<para
>O <guilabel
>Formato</guilabel
> da lista de reprodução poderá ser o <guilabel
>M3U</guilabel
>, <guilabel
>PLS</guilabel
> ou <guilabel
>XSPF</guilabel
>. </para>
<para
>Se a opção <guibutton
>Incluir apenas os ficheiros seleccionados</guibutton
> estiver assinalada, só serão incluídos os ficheiros seleccionados na lista de reprodução. Se uma dada pasta for seleccionada, serão seleccionados todos os seus ficheiros. Se esta opção de marcação não estiver assinalada, todos os ficheiros de áudio serão incluídos na lista de reprodução. </para>
<para
>O <guibutton
>Ordenar pelo nome do ficheiro</guibutton
> selecciona o caso normal, onde os ficheiros são ordenados pelo nome do ficheiro. Com a opção <guibutton
>Ordenar pelo campo da marca</guibutton
>, é possível ordenar por um dado texto de formato com os valores dos campos das marcas. Por exemplo, o "<userinput
>%{track.3}</userinput
>" pode ser usado para ordenar pelo número da faixa (o "<userinput
>.3</userinput
>" é usado para obter três algarismos com zeros iniciais, dado que são usados textos nas ordenação). Também é possível usar vários campos, <abbrev
>p.ex.</abbrev
> "<userinput
>%{genre}%{year}</userinput
>" para ordenar por um texto composto pelo género e ano. </para>
<para
>Os elementos da lista de reprodução terão locais relativos ou absolutos, dependendo se as opções <guibutton
>Usar uma localização relativa para os ficheiros na lista de reprodução</guibutton
> ou a <guibutton
>Usar a localização completa para os ficheiros na lista de reprodução</guibutton
> estiver definida. </para>
<para
>Quando estiver assinalada a opção <guibutton
>Escrever apenas a lista de ficheiros</guibutton
>, a lista de reprodução só irá conter as localizações dos ficheiros. Para gerar uma lista estendida com informações adicionais, poderá definir um texto de formato com o controlo <guibutton
>Gravar a informação com</guibutton
>. </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>Q</keycap
></keycombo
> </shortcut
> <guimenu
>Ficheiro</guimenu
> <guimenuitem
>Sair</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Sai da aplicação.</action
></para
></listitem>
</varlistentry>

</variablelist>
</para>

</sect1>

<sect1 id="edit-menu">
<title
>O Menu Editar</title>
<para>
<variablelist>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Alt;<keycap
>A</keycap
></keycombo
> </shortcut
> <guimenu
>Editar</guimenu
> <guimenuitem
>Seleccionar Tudo</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Selecciona todos os ficheiros.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>Shift</keycap
><keycap
>A</keycap
></keycombo
> </shortcut
> <guimenu
>Editar</guimenu
> <guimenuitem
>Deseleccionar</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Deselecciona todos os ficheiros.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Editar</guimenu
> <guimenuitem
>Seleccionar Tudo na Pasta</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Selecciona todos os ficheiros na pasta actual.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Alt;<keycap
>Cima</keycap
></keycombo
> </shortcut
> <guimenu
>Editar</guimenu
> <guimenuitem
>Ficheiro Anterior</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Selecciona o ficheiro anterior.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Alt;<keycap
>Baixo</keycap
></keycombo
> </shortcut
> <guimenu
>Editar</guimenu
> <guimenuitem
>Ficheiro Seguinte</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Selecciona o ficheiro seguinte.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>F</keycap
></keycombo
> </shortcut
> <guimenu
>Editar</guimenu
> <guimenuitem
>Procurar...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Procura por determinados textos nos nomes dos ficheiros e nas marcas. A janela <guilabel
>Procurar</guilabel
> é um sub-conjunto da janela <guilabel
>Substituir</guilabel
>, a qual está descrita em baixo. </para
></listitem>
</varlistentry>

<varlistentry id="find-replace">
<term
><menuchoice
><shortcut
> <keycombo
>&Ctrl;<keycap
>R</keycap
></keycombo
> </shortcut
> <guimenu
>Editar</guimenu
> <guimenuitem
>Substituir...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Esta função abre uma janela para procurar e substituir os textos nos nomes dos ficheiros e nas marcas. O conjunto de pacotes onde é efectuada a pesquisa poderá ser restrito se desactivar a opção <guilabel
>Seleccionar tudo</guilabel
> e seleccionar os pacotes que devem ser pesquisados. Também existem opções de pesquisa para poder procurar para trás, para distinguir a capitalização e para usar as expressões regulares.</para>
<para
>Dependendo do número de ficheiros, a pesquisa poderá demorar algum tempo, como tal poderá ser interrompida se fechar a janela.</para
></listitem>
</varlistentry>

</variablelist>
</para>
</sect1>

<sect1 id="tools-menu">
<title
>O Menu Ferramentas</title>
<para>
<variablelist>

<varlistentry id="apply-filename-format">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Aplicar o Formato do Nome do Ficheiro</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Quando a opção <guilabel
>Aplicar automaticamente o formato</guilabel
> estiver desligada para o formato de nomes dos ficheiros na janela de configuração, este item do menu pode ser usado para <action
>aplicar o formato configurado aos nomes dos ficheiros seleccionados</action
>. Isto também pode ser usado para verificar se os nomes dos ficheiros estão em conformidade com o formato configurado, aplicando o formato a todos os ficheiros gravados e depois verificando se alguns dos ficheiros foram modificados (e, deste modo, marcados com um símbolo de disco na lista de ficheiros). </para
></listitem>
</varlistentry>

<varlistentry id="apply-tag-format">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Aplicar o Formato das Marcas</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Quando a opção <guilabel
>Aplicar automaticamente o formato</guilabel
> estiver desligada para o formato das marcas na janela de configuração, este item do menu pode ser usado para <action
>aplicar o formato configurado às marcas dos ficheiros seleccionados</action
>. Isto também pode ser usado para verificar se as marcas estão em conformidade com o formato configurado, aplicando o formato a todos os ficheiros gravados e depois verificando se alguns dos ficheiros foram modificados (e, deste modo, marcados com um símbolo de disco na lista de ficheiros). </para
></listitem>
</varlistentry>

<varlistentry id="apply-text-encoding">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Aplicar a Codificação do Texto</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Define a <guilabel
>Codificação de texto</guilabel
> seleccionada em <menuchoice
><guimenu
>Configuração</guimenu
><guimenuitem
>Configurar o &kid3;... </guimenuitem
><guimenuitem
>secção de Marcas</guimenuitem
><guimenuitem
>página da Marca 2</guimenuitem
></menuchoice
> para todos os ficheiros seleccionados. Se estiver seleccionado o UTF8, será usado o UTF16 para as marcas ID3v2.3.0, dado que o UTF8 não é suportado para este formato.</para
></listitem>
</varlistentry>

<varlistentry id="rename-directory">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Mudar o Nome da Pasta...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Esta janela oferece a possibilidade de mudar automaticamente de nome a pasta aberta de momento, de acordo com as marcas nos ficheiros. Estão pré-configurados diversos formatos para incluir informações sobre o artista, o álbum e o ano no nome da pasta. Também é possível definir um formato personalizado e <guibutton
>Editar</guibutton
> a lista de formatos disponíveis. São usados os seguintes códigos especiais para inserir os valores das marcas no nome da pasta: </para>

<itemizedlist>
<listitem
><para
>%s %{title} Título (Música)</para
></listitem>
<listitem
><para
>%a %{artist} Artista</para
></listitem>
<listitem
><para
>%l %{album} Álbum</para
></listitem>
<listitem
><para
>%c %{comment} Comentário</para
></listitem>
<listitem
><para
>%y %{year} Ano</para
></listitem>
<listitem
><para
>%t %{track} Faixa (<abbrev
>p.ex.</abbrev
> 01)</para
></listitem>
<listitem
><para
>%t %{track.n} Faixa com o tamanho do campo 'n' (<abbrev
>p.ex.</abbrev
> 001 para %{track.3})</para
></listitem>
<listitem
><para
>%T %{tracknumber} Faixa (sem os zeros iniciais, <abbrev
>p.ex.</abbrev
> 1)</para
></listitem>
<listitem
><para
>%g %{genre} Género</para
></listitem>
<listitem
><para
>%{dirname} Nome da pasta (<abbrev
>p.ex.</abbrev
> %{year" "}%{dirname} irá anteceder o ano ao nome da pasta actual)</para
></listitem>
<listitem
><para
>%{max-year} O valor máximo do ano encontrado para esta pasta; também poderá ser usado com outros códigos que não o "year"</para
></listitem>
<listitem
><para
>%{min-year} O valor mínimo do ano encontrado para esta pasta</para
></listitem>
<listitem
><para
>%{unq-year} O valor único do ano encontrado para esta ou vazio se não for único</para
></listitem>
</itemizedlist>

<para
>Se for encontrado um separador de pastas "/" no formato, são criadas várias pastas. Se quiser criar uma nova pasta em vez de mudar o nome da pasta actual, seleccione <guilabel
>Criar uma Pasta</guilabel
> em vez de <guilabel
>Mudar o Nome da Pasta</guilabel
>. A <guilabel
>Origem</guilabel
> da informação da marca poderá ser escolhida entre <guilabel
>Da Marca 1 e Marca 2</guilabel
>, <guilabel
>Da Marca 1</guilabel
> e <guilabel
>Da Marca 2</guilabel
>. Poderá ter uma antevisão da operação de mudança de nome efectuada no primeiro ficheiro nas secções <guilabel
>De</guilabel
> e <guilabel
>Para</guilabel
> da janela. </para>
<para
>Poderá mudar o nome de várias pastas se as seleccionar. </para
></listitem>
</varlistentry>

<varlistentry id="number-tracks">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Numerar as Faixas...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Se os números de faixa nas marcas não estiverem definidos ou tiverem valores errados, esta função poderá <action
>numerar as faixas de forma automática, por ordem ascendente</action
>. O número inicial poderá ser definido na janela. Se só tiver de numerar parte das faixas, as mesmas devem estar seleccionadas. </para
><para
>Quando o <guilabel
>Número total de faixas</guilabel
> estiver assinalado, também será definido o número de faixas nas marcas. </para
><para
>É possível numerar as faixas por várias pastas. As pastas têm de estar expandidas e seleccionadas. </para
><para
>Se a opção <guilabel
>Repor o contador para cada pasta</guilabel
> estiver assinalada, a numeração de faixas é reiniciada com o número indicado para cada pasta, sempre que estiverem seleccionadas várias pastas. </para
><para
>A janela de numeração das faixas também pode ser usada para formatar os números de faixas existentes sem modificar os valores quando a opção de marcação à esquerda do <guilabel
>Número de início</guilabel
> estiver desactivada. O número total de faixas será adicionado se a opção de marcação correspondente estiver activa, o que poderá ser usado para definir o total de todas as faixas seleccionadas. Se só for desejada a formatação dos números existentes, esta opção de marcação também tem de ser desactivada. </para
></listitem>
</varlistentry>

<varlistentry id="filter">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Filtrar...</guimenuitem
> </menuchoice
></term>
<listitem>
<para
>O filtro poderá ser usado para mostrar apenas os ficheiros que correspondem a determinados critérios. Isto é útil se quiser organizar uma colecção grande e só editar os ficheiros que não estejam no esquema desejado. A expressão que define quais os valores a apresentar usa os mesmos códigos de formato que são usados no formato dos nomes de ficheiros, na importação e na exportação. </para>

<itemizedlist>
<listitem
><para
>%s %{title} Título (Música)</para
></listitem>
<listitem
><para
>%a %{artist} Artista</para
></listitem>
<listitem
><para
>%l %{album} Álbum</para
></listitem>
<listitem
><para
>%c %{comment} Comentário</para
></listitem>
<listitem
><para
>%y %{year} Ano</para
></listitem>
<listitem
><para
>%t %{track} Faixa (<abbrev
>p.ex.</abbrev
> 01)</para
></listitem>
<listitem
><para
>%t %{track.n} Faixa com o tamanho do campo 'n' (<abbrev
>p.ex.</abbrev
> 001 para %{track.3})</para
></listitem>
<listitem
><para
>%T %{tracknumber} Faixa (sem os zeros iniciais, <abbrev
>p.ex.</abbrev
> 1)</para
></listitem>
<listitem
><para
>%g %{genre} Género</para
></listitem>
<listitem
><para
>%f %{file} Nome do ficheiro</para
></listitem>
<listitem
><para
>%p %{filepath} Localização absoluta do ficheiro</para
></listitem>
<listitem
><para
>%e %{extension} Extensão do ficheiro</para
></listitem>
<listitem
><para
>%O %{tag1} O formato da marca 1 (ID3v1.1 ou vazio se inexistente)</para
></listitem>
<listitem
><para
>%o %{tag2} O formato da marca 2 (ID3v2.3.0, ID3v2.4.0, ID3v2.2.0, ID3v2.2.1, Vorbis, APE, MP4, ASF ou vazio se inexistente)</para
></listitem>
<listitem
><para
>%b %{bitrate} Taxa de dados em kbit/s</para
></listitem>
<listitem
><para
>%v %{vbr} VBR ou vazio (apenas para o ID3v2.3 com a id3lib)</para
></listitem>
<listitem
><para
>%r %{samplerate} Taxa de amostragem em Hz</para
></listitem>
<listitem
><para
>%m %{mode} Modo do canal (Estéreo ou Estéreo Conjunto)</para
></listitem>
<listitem
><para
>%h %{channels} Número de canais (1 ou 2)</para
></listitem>
<listitem
><para
>%k %{codec} Codificador (<abbrev
>p.ex.</abbrev
> MPEG 1 Nível 3, MP4, Ogg Vorbis, FLAC, MPC, APE, ASF, AIFF, WAV)</para
></listitem>
<listitem
><para
>%w %{marked} Marcado; é igual a 1 se o ficheiro estiver marcado (<abbrev
>p.ex.</abbrev
> por estar truncado ou a violar a norma), sendo vazio em caso contrário</para
></listitem>
<listitem
><para
>%1a %1{artist}, ... Use o prefixo 1 para obter os valores da marca 1</para
></listitem>
<listitem
><para
>%2a %2{artist}, ... Use o prefixo 2 para obter os valores da marca 2</para
></listitem>
</itemizedlist>

<para
>Estes códigos são substituídos pelos valores do ficheiro, sendo que os textos resultantes podem ser comparados com as seguintes operações: </para>
<itemizedlist>
<listitem
><para
>t1 equals t2: verdadeiro se o t1 e o t2 forem iguais.</para
></listitem>
<listitem
><para
>t1 contains t2: verdadeiro se o t1 conter o t2, <abbrev
>i.e.</abbrev
> o t2 for um sub-texto de t1.</para
></listitem>
<listitem
><para
>t matches er: verdadeiro se o t corresponder à expressão regular er.</para
></listitem>
</itemizedlist>
<para
>As expressões verdadeiras são substituídas por 1 e as falsas por 0. Os valores verdadeiros são representados como 1, true, on e yes, enquanto os valores falsos são por 0, false, off e no. As operações booleanas são o 'not', 'and' e 'or' (por esta ordem de precedência) e podem ser agrupadas com parêntesis. </para>
<para
>Algumas regras de filtragem são predefinidas e podem servir de exemplos para as suas próprias expressões: </para>

<variablelist>
<varlistentry
><term
>Tudo</term
><listitem>
<para
>Quando a lista de ficheiros estiver filtrada - isso aparece como "[filtrado]" no título da janela - e caso deseje mostrar todos os ficheiros de novo, a filtragem pode ser revertida com este filtro. Ela usa uma expressão vazia, mas um valor verdadeiro terá o mesmo efeito. </para>
</listitem
></varlistentry>

<varlistentry
><term
>Inconsistência da Marca do Nome do Ficheiro</term
><listitem>
<para
><userinput
>not (%{filepath} contains "%{artist} - %{album}/%{track} %{title}") </userinput
></para>
<para
>Testa de a localização do ficheiro está em conformidade com o formato de nomes de ficheiros. Esta regra é adaptada automaticamente se o formato do nome do ficheiro mudar. </para>
</listitem
></varlistentry>

<varlistentry
><term
>Sem Marca 1</term
><listitem>
<para
><userinput
>%{tag1} equals "" </userinput
></para>
<para
>Mostra apenas os ficheiros que não tiverem uma marca 1.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Sem Marca 2</term
><listitem>
<para
><userinput
>%{tag2} equals "" </userinput
></para>
<para
>Mostra apenas os ficheiros que não tiverem uma marca 2.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Marca de ID3v2.3.0</term
><listitem>
<para
><userinput
>%{tag2} equals "ID3v2.3.0" </userinput
></para>
<para
>Mostra apenas os ficheiros que tiverem uma marca de ID3v2.3.0.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Marca de ID3v2.4.0</term
><listitem>
<para
><userinput
>%{tag2} equals "ID3v2.4.0" </userinput
></para>
<para
>Mostra apenas os ficheiros que tiverem uma marca de ID3v2.4.0.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Marca 1 != Marca 2</term
><listitem>
<para
><userinput
>not (%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist} equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals %2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre}) </userinput
></para>
<para
>Mostra os ficheiros com diferenças entre a marca 1 e a marca 2.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Marca 1 == Marca 2</term
><listitem>
<para
><userinput
>%1{title} equals %2{title} and %1{album} equals %2{album} and %1{artist} equals %2{artist} and %1{comment} equals %2{comment} and %1{year} equals %2{year} and %1{track} equals %2{track} and %1{genre} equals %2{genre} </userinput
></para>
<para
>Mostra os ficheiros com a marca 1 e a marca 2 idênticas.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Incompleto</term
><listitem>
<para
><userinput
>%{title} equals "" or %{artist} equals "" or %{album} equals "" or %{year} equals "" or %{tracknumber} equals "" or %{genre} equals "" </userinput
></para>
<para
>Mostra os ficheiros com valores vazios nas marcas-padrão (title, artist, album, date, track number, genre).</para>
</listitem
></varlistentry>

<varlistentry
><term
>Sem Imagem</term
><listitem>
<para
><userinput
>%{picture} equals "" </userinput
></para>
<para
>Mostra apenas os ficheiros que não tiverem uma imagem.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Marcado</term
><listitem>
<para
><userinput
>not (%{marked} equals "") </userinput
></para>
<para
>Mostra apenas os ficheiros que estiverem marcados por violarem a norma ID3, estejam truncados ou a imagem for demasiado grande.</para>
</listitem
></varlistentry>

<varlistentry
><term
>Filtro Personalizado</term
><listitem>
<para
>Para adicionar o seu próprio filtro, seleccione este item. Por exemplo, se quiser um filtro por artistas que comecem por "The", substitua o "Filtro Personalizado" pelo nome "Bandas 'The'" e carregue em <keycap
>Enter</keycap
>. Depois indique a seguinte expressão no campo de texto: </para>
<para
><userinput
>%{artist} matches "The.*" </userinput
></para>
<para
>Depois carregue em <guibutton
>Gravar a Configuração</guibutton
>. Carregue em <guibutton
>Aplicar</guibutton
> para filtrar os ficheiros. Todos os ficheiros processados são apresentados no campo de texto, com um "+" para as correspondências ao filtro e um "-" para os outros. Quando terminar só os ficheiros com um artista que comece por "The" são apresentados, assim como o título da janela fica marcada como "[filtrado]". </para>
</listitem
></varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry id="convert-to-id3v24">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Converter o ID3v2.3 para ID3v2.4</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Se existirem algumas marcas de ID3v2.3 nos ficheiros seleccionados, as mesmas serão <action
>convertidas para marcas de ID3v2.4</action
>. Os pacotes que não forem suportados pela TagLib serão descartados. Só os ficheiros sem modificações por gravar é que serão convertidos. </para
></listitem>
</varlistentry>

<varlistentry id="convert-to-id3v23">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Converter o ID3v2.4 para ID3v2.3</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Se existirem algumas marcas de ID3v2.4 nos ficheiros seleccionados, as mesmas serão <action
>convertidas para marcas de ID3v2.3</action
>. Os pacotes que não forem suportados pela TagLib serão descartados. Só os ficheiros sem modificações por gravar é que serão convertidos. </para
></listitem>
</varlistentry>

<varlistentry id="play">
<term
><menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Reproduzir</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Isto abre uma barra de ferramentas simples para tocar ficheiros de áudio. Contém botões para as operações básicas  (<guibutton
>Reproduzir/Pausa</guibutton
>, <guibutton
>Parar a reprodução</guibutton
>, <guibutton
>Faixa Anterior</guibutton
>, <guibutton
>Faixa Seguinte</guibutton
>, <guibutton
>Fechar</guibutton
>), barras de posição e de volume e um mostrador da posição actual. Se tiver seleccionado vários ficheiros, as faixas seleccionadas serão reproduzidas, caso contrário serão reproduzidos todos os ficheiros. </para
></listitem>
</varlistentry>

</variablelist>
</para>
</sect1>

<sect1 id="settings-menu">
<title
>O Menu Configuração</title>
<para>
<variablelist>

<varlistentry>
<term
><menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Mostrar a Barra de Ferramentas</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Activa/desactiva a apresentação da barra de ferramentas.</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Mostrar a Barra de Estado</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Comuta a apresentação da barra de estado</action
>, que mostra as acções mais longas como a abertura ou gravação de uma dada pasta.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Mostrar a Imagem</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Comuta a apresentação da imagem de antevisão das capas do álbum.</action>
</para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Auto-Esconder as Marcas</guimenuitem
> </menuchoice
></term>
<listitem
><para
>As marcas vazias ficam automaticamente escondidas se esta opção estiver activa. As secções <guilabel
>Ficheiro</guilabel
>, <guilabel
>Marca 1</guilabel
> e <guilabel
>Marca 2</guilabel
> poderão ser fechadas e expandidas manualmente se carregar nos botões <guibutton
>-</guibutton
>/<guibutton
>+</guibutton
> respectivos. </para
></listitem>
</varlistentry>

<varlistentry id="configure-shortcuts">
<term
><menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar as Teclas de Atalho...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Abre uma janela para atribuir atalhos de teclado à maior parte das funções do programa. Existem até funções sem menu ou botão disponível, <abbrev
>p.ex.</abbrev
> ficheiro seguinte, ficheiro anterior, seleccionar tudo. </para>
 
</listitem>
</varlistentry>

<varlistentry id="configure-kid3">
<term
><menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o &kid3;...</guimenuitem
> </menuchoice
></term>
<listitem
><para
>Abre a <action
>janela de configuração</action
>, que consiste nas páginas das marcas, ficheiros, acções do utilizador e configuração da rede. </para>
<para
>As opções específicas das marcas poderão ser encontradas na página <guilabel
>Marcas</guilabel
>, que por sua vez está dividida em quatro páginas para a <guilabel
>Marca 1</guilabel
>, <guilabel
>Marca 2</guilabel
>, <guilabel
>Marca 3</guilabel
> e <guilabel
>Todas as Marcas</guilabel
>. </para>
<para
>Se a opção <guilabel
>Marcar os campos truncados</guilabel
> estiver assinalada, os campos de ID3v1.1 truncados ficarão marcados a vermelho. Os campos de texto das marcas ID3v1.1 só poderão ter 30 caracteres, assim como o comentário só poderá ter 28 caracteres. Do mesmo modo, o género e os números de faixas são restritos, pelo que os campos poderão ficar truncados quando forem importados ou transferidos a partir do ID3v2. Os campos truncados e o nome do ficheiro ficarão marcados a vermelho, sendo que a marca será removida após editar o campo. </para>
<para
>Com a <guilabel
>Codificação do texto</guilabel
> para o <guilabel
>ID3v1</guilabel
>, é possível definir o conjunto de caracteres usado nas marcas ID3v1. Esta codificação é supostamente a ISO-8859-1, pelo que se recomenda manter este valor predefinido. Contudo, existem marcas com codificações diferentes, pelo que a mesma pode ser definida aqui e as marcas ID3v1 possam então ser copiadas para o ID3v2, que suporta o Unicode. </para>
<para
>A opção de marcação <guilabel
>Usar o formato faixa/número total de faixas</guilabel
> controla se o campo do número da faixa das marcas ID3v2 contém apenas o número da faixa ou também o número total de faixas na pasta. </para>
<para
>Quando estiver assinalada a opção <guilabel
>Género como texto em vez de texto numérico</guilabel
>, todos os géneros do ID3v2 serão guardados como uma sequência de texto, mesmo que exista um código correspondente para os géneros de ID3v1. Se esta opção não estiver activa, os géneros para os quais exista um código de ID3v1 são guardados como o número de código do género (entre parêntesis para o ID3v2.3). Como tal, o género Metal está guardado como "Metal" ou "(9)", dependendo desta opção. Os géneros que não constem na lista de géneros ID3v1 são sempre guardados como uma sequência de texto. O objectivo desta opção é melhorar a compatibilidade com os dispositivos que não interpretam correctamente os códigos de géneros. </para>
<para
>Quando a opção <guilabel
>Ficheiros WAV com bloco de ID3 em minúsculas</guilabel
> estiver assinalada, o bloco de RIFF usado para guardar as marcas ID3v2 nos ficheiros WAV terá o nome "id3 " em vez de "ID3 ". Por omissão, o &kid3; e outras aplicações que usam a TagLib aceitam tanto a versão em maiúsculas como em minúsculas ao ler os ficheiros WAV, mas irão usar a versão "ID3 " quando gravar as marcas ID3v2 nos ficheiros WAV. Dado que existem outras aplicações que só aceitam a versão "id3 " (<abbrev
>p.ex.</abbrev
> JRiver Media Center e foobar2000), esta opção poderá ser usada para criar marcas que possam ser lidas por essas aplicações. </para>
<para
>Quando a opção <guilabel
>Marcar as violações da norma</guilabel
> estiver assinalada, os campos de ID3v2 que violem os padrões serão marcados a vermelho. Os detalhes sobre a violação aparecerão numa dica: </para>
<itemizedlist>
<listitem
><para
>Deve ser único</para
></listitem>
<listitem
><para
>Não é permitida uma mudança de linha</para
></listitem>
<listitem
><para
>Não é permitido o retorno de linha</para
></listitem>
<listitem
><para
>O dono não pode estar em branco</para
></listitem>
<listitem
><para
>Deve ser numérico</para
></listitem>
<listitem
><para
>Deve ser numérico ou número/total</para
></listitem>
<listitem
><para
>O formato é DDMM</para
></listitem>
<listitem
><para
>O formato é HHMM</para
></listitem>
<listitem
><para
>O formato é AAAA</para
></listitem>
<listitem
><para
>Deve começar por um ano e um espaço</para
></listitem>
<listitem
><para
>Deve ser uma data/hora no formato ISO 8601</para
></listitem>
<listitem
><para
>Deve ser uma nota musical, 3 caracteres, A-G, b, #, m, o</para
></listitem>
<listitem
><para
>Deve ser um código de língua ISO 639-2, 3 caracteres minúsculos</para
></listitem>
<listitem
><para
>Deve ser um código ISRC de 12 caracteres</para
></listitem>
<listitem
><para
>Deve ser uma lista de textos separados por '|'</para
></listitem>
<listitem
><para
>Tem espaços em excesso</para
></listitem>
</itemizedlist>
<para
>Os documentos da norma ID3 estão disponíveis 'online': </para>
<itemizedlist>
<listitem
><para
><ulink url="http://id3.org/id3v2.3.0"
>Marca ID3 na versão 2.3.0</ulink
></para
></listitem>
<listitem
><para
><ulink url="http://id3.org/id3v2.4.0-structure"
>Marca ID3 na versão 2.4.0 - Estrutura Principal</ulink
></para
></listitem>
<listitem
><para
><ulink url="http://id3.org/id3v2.4.0-frames"
>Marca ID3 na versão 2.4.0 - Pacotes Nativos</ulink
></para
></listitem>
</itemizedlist>
<para
>A <guilabel
>Codificação do texto</guilabel
> define a codificação predefinida usada para os pacotes ID3v2 e poderá ser configurada como <guilabel
>ISO-8859-1</guilabel
>, <guilabel
>UTF16</guilabel
> ou <guilabel
>UTF8</guilabel
>. O <guilabel
>UTF8</guilabel
> não é válido para os pacotes ID3v2.3.0; se estiver configurado, será usado em alternativa o <guilabel
>UTF16</guilabel
>. Para os pacotes de ID3v2.4.0, todas as três codificações são permitidas. </para>
<para
>A <guilabel
>Versão usada para as marcas novas</guilabel
> determina se as marcas ID3v2 novas são criadas na versão 2.3.0 ou 2.4.0. </para>
<para
>Os <guilabel
>Algarismos do número de faixa</guilabel
> é o número de algarismos nos campos do Número de Faixa. Os zeros iniciais são usados para preencher. Por exemplo, com um valor igual a 2, o número de faixa 5 fica igual a "05". </para>
<para
>A lista <guilabel
>Nome do campo de comentário</guilabel
> só é relevante para os ficheiros Ogg/Vorbis e FLAC e define o nome do campo que é usado para os comentários. As diferentes aplicações parecem usar nomes diferentes, sendo por exemplo usado no <application
>XMMS</application
> o "<literal
>COMMENT</literal
>", enquanto o &amarok; usa o "<literal
>DESCRIPTION</literal
>". </para>
<para
>O formato das imagens nos ficheiros Ogg/Vorbis é determinado pelo campo <guilabel
>Nome do campo de imagem</guilabel
>, o qual poderá ser igual a "<literal
>METADATA_BLOCK_PICTURE</literal
>" ou "<literal
>COVERART</literal
>". O primeiro faz parte da norma oficial e usa o mesmo formato que as imagens nas marcas FLAC. O COVERART é uma forma mais antiga e não oficial de incluir imagens nos comentários do Vorbis. Pode ser usado por compatibilidade com os leitores antigos. </para>
<para
>Se a opção <guilabel
>Marcar se maior que (bytes)</guilabel
> estiver activada, os ficheiros que contêm imagens de capa incorporadas que ultrapassem o tamanho indicado em 'bytes' ficarão marcados a vermelho. Isto pode ser usado para descobrir os ficheiros que têm imagens demasiado grandes e que, por isso, possam não ser aceites por algumas aplicações e leitores. O valor por omissão é de 131072 bytes (128 KB). </para>
<para
>Os <guilabel
>Géneros Personalizados</guilabel
> poderão ser usados para definir géneros que não estejam disponíveis na lista de géneros-padrão, <abbrev
>p.ex.</abbrev
> "Gothic Metal". Esses géneros personalizados irão aparecer na lista <guilabel
>Género</guilabel
> da <guilabel
>Marca 2</guilabel
>. Para as marcas ID3v1.1, só poderão ser usados os géneros predefinidos. </para>
<para
>A lista de géneros personalizados também poderá ser usada para reduzir o número de géneros disponíveis na lista <guilabel
>Género</guilabel
> aos que são tipicamente usados. Se a sua colecção consistir principalmente em músicas dos géneros Metal, Gothic Metal, Ancient e Hard Rock, poderá inserir esses géneros e marcar a opção <guilabel
>Mostrar apenas os géneros personalizados</guilabel
>. A lista <guilabel
>Género</guilabel
> da <guilabel
>Marca 2</guilabel
> só irá conter esses quatro géneros e não terá de pesquisar pela lista completa de géneros deles. Neste exemplo, só irá aparecer Metal e Hard Rock na lista de géneros da marca 1, dado que esses itens de géneros personalizados ainda são géneros-padrão. Se a opção <guilabel
>Mostrar apenas os géneros personalizados</guilabel
> não estiver activa, os géneros personalizados poderão ser encontrados no fim da lista de géneros. </para>
<para
>Os <guilabel
>Pacotes de Acesso Rápido</guilabel
> definem quais os tipos de pacotes que ficam sempre visíveis na secção da <link linkend="tag2"
>Marca 2</link
>. Esses pacotes poderão então ser adicionados sem usar primeiro o botão <guibutton
>Adicionar</guibutton
>. A ordem desses pacotes de acesso rápido poderá ser alterada se arrastar os itens respectivos. </para>
<para
>A lista <guilabel
>Nome do campo de número de faixa</guilabel
> só relevante para o RIFF INFO e define o nome do campo usado para os números de faixas. Os números de faixa não fazem parte da norma RIFF original, sendo que existem aplicações que usam o "<literal
>ITRK</literal
>" e outras o "<literal
>IPRT</literal
>". </para>
<para
>O <guilabel
>Formato das Marcas</guilabel
> contém opções para o formato das marcas. Quando a opção <guilabel
>Aplicar automaticamente o formato</guilabel
> estiver assinalada, a configuração do formato é usada automaticamente ao editar o texto nos campos de edição. A <guilabel
>Validação</guilabel
> activa algumas validações nos controlos com os valores da faixa/total e data/hora. A <guilabel
>Conversão de capitalização</guilabel
> pode ser configurada como <guilabel
>Sem alterações</guilabel
>, <guilabel
>Tudo em minúsculas</guilabel
>, <guilabel
>Tudo em maiúsculas</guilabel
>, <guilabel
>Primeira letra maiúscula</guilabel
> ou <guilabel
>Todas as primeiras letras maiúsculas</guilabel
>. Para usar uma conversão com suporte regional entre maiúsculas e minúsculas, poderá seleccionar uma região na lista abaixo. A lista de substituições de textos poderá ser configuradas com associações de texto arbitrárias. Para adicionar uma nova associação, seleccione a célula <guilabel
>De</guilabel
> de uma linha e introduza o texto a substituir, indo depois à coluna <guilabel
>Para</guilabel
> e indicando o texto de substituição. Quando o texto a substituir começar por uma barra ("/"), é usada uma expressão regular. Para as expressões regulares que tiverem grupos de captura, as ocorrências de \1, \2, ... no campo <guilabel
>Para</guilabel
> são substituídas pelo texto capturado no grupo de captura correspondente. Para remover uma associação, configure a célula <guilabel
>de</guilabel
> como um valor vazio (<abbrev
>p.ex.</abbrev
> escrevendo um espaço e depois apagando-o). A inserção e remoção de linhas também é possível com o menu de contexto que aparece quando carregar no botão <mousebutton
>direito</mousebutton
> do rato. A substituição só fica activa se a opção de marcação <guilabel
>Substituição de texto</guilabel
> estiver assinalada. </para>

<para
>A tabela na <guilabel
>Classificação</guilabel
> contém a associação das classificações com estrelas aos valores efectivos que são guardados na marca. Os pacotes com informação de classificação aparecem na linha Classificação da <link linkend="table-frame-list"
>lista de pacotes</link
>. Para esses pacotes, a classificação poderá ser definida se indicar um número de estrelas até cinco. Os diferentes formatos de marcas e diferentes aplicações usam diferentes valores para associar a classificação por estrelas ao valor guardado na marca. Para mostrar o número correcto de estrelas, o &kid3; irá procurar por um mapa nesta tabela. A chave para procurar nesse mapa é o nome do pacote, como por exemplo "RATING" se for usado nos comentários do Vorbis ou "IRTD" para o INFO do RIFF. Para as marcas de ID3v2, é usada uma chave composta que consiste no ID do pacote "POPM" da Medicação de Popularidade e no seu campo "E-mail", separados por um ponto. Como tal, existem diferentes chaves para o ID3v2, <abbrev
>p.ex.</abbrev
> "POPM.Windows Media Player 9 Series" para a associação usadas pelo Windows Media Player e pelo Explorer, ou simplesmente "POPM" para os pacotes POPM com um campo de "E-mail" vazio. Dado que poderão existir vários itens para o "POPM", a sua ordem é importante. Quando o &kid3; adiciona um novo pacote de Medição de Popularidade, irá usar o primeiro item "POPM" para determinar o valor a ser gravado no campo "E-mail". Este valor irá então definir a associação a usar para as classificações por estrelas. É usado o primeiro item também se não for encontradas nenhuma chave, sendo assim o item predefinido. </para>
<para
>Para além da coluna <guilabel
>Nome</guilabel
> que contém as chaves, a tabela tem colunas da <guilabel
>1</guilabel
> até à <guilabel
>5</guilabel
> para os valores a guardar quando é atribuído o número correspondente de estrelas. De igual forma, os valores determinam o número de estrelas que são apresentadas para o valor guardado no pacote. Por exemplo, a linha na tabela abaixo contém os valores 1, 64, 128, 196, 255. Os limites para apresentar os números de estrelas situam-se entre estes valores e são compatíveis com que o &Windows; Explorer usa. </para>

<table id="table-rating">
  <title
>Elemento na Tabela de Classificação</title>
  <tgroup cols="6">
    <thead>
      <row
><entry
>Nome</entry
><entry
>1</entry
> <entry
>2</entry
>  <entry
>3</entry
>  <entry
>4</entry
>  <entry
>5</entry
></row>
    </thead>
    <tbody>
      <row
><entry
>POPM</entry
><entry
>1</entry
><entry
>64</entry
><entry
>128</entry
><entry
>196</entry
><entry
>255</entry
></row>
      <row
><entry
>Intervalo</entry
><entry
>1-31</entry
><entry
>32-95</entry
><entry
>96-159</entry
><entry
>160-223</entry
><entry
>224-255</entry
></row>
    </tbody>
  </tgroup>
</table>

<para
>Na página <guilabel
>Ficheiros</guilabel
>, a opção <guilabel
>Carregar os últimos ficheiros abertos</guilabel
> poderá ser assinalada para que o &kid3; abra e seleccione o último ficheiro seleccionado quando for iniciado da próxima vez. A opção <guilabel
>Preservar a data do ficheiro</guilabel
> pode ser assinalada para preservar a data de modificação do ficheiro. O <guilabel
>Nome do ficheiro da capa</guilabel
> define o nome que é sugerido quando uma imagem incorporada for exportada para um ficheiro. Com a opção <guilabel
>Codificação de texto (Exportar, Lista de Reprodução)</guilabel
>, poderá definir a codificação usada para gravar os ficheiros. O valor predefinido <guilabel
>Sistema</guilabel
> poderá ser alterado por exemplo se as listas de reprodução tiverem de ser usadas num dispositivo diferente. </para>
<para
>Se a opção <guilabel
>Marcar as modificações</guilabel
> estiver activa, os campos alterados estão marcados com um fundo da legenda em cinzento claro. </para>
<para
>A secção <guilabel
>Lista de Ficheiros</guilabel
> define quais os ficheiros que aparecem na lista de ficheiros. Poderá usar um <guilabel
>Filtro</guilabel
> para restringir os itens nesta lista para os ficheiros com as extensões suportadas. Para indicar de forma explícita quais as pastas a apresentar na lista de ficheiros ou para excluir certas pastas, poderá usar as opções <guilabel
>Incluir as pastas</guilabel
> e <guilabel
>Excluir as pastas</guilabel
>. Poderão contém caracteres especiais, como por exemplo <filename
>*/Música/*</filename
> para incluir apenas a pasta <filename
>Música</filename
> ou <filename
>*/iTunes/*</filename
> para excluir a pasta do iTunes da lista de ficheiros. Se tiver de usar várias expressões deste tipo, as mesmas poderão ser separadas por espaços ou pontos-e-vírgulas. </para>
<para
>Os botões <guibutton
>Nome do ficheiro a partir da marca</guibutton
> e <guibutton
>Marca a partir do nome do ficheiro</guibutton
> na secção <guilabel
>Formato</guilabel
> abrem janelas para editar os formatos que ficam disponíveis na lista <guilabel
>Formato</guilabel
> (com setas para cima e para baixo), as quais poderão ser encontradas na secção <link linkend="file"
>Ficheiro</link
> da janela principal. </para>
<para
>O <guilabel
>Formato dos Nomes de Ficheiros</guilabel
> contém opções para o formato dos nomes dos ficheiros. Estão disponíveis as mesmas opções que no <guilabel
>Formato das Marcas</guilabel
>. </para>
<para
>A página de <guilabel
>Acções do Utilizador</guilabel
> contém uma tabela com os comandos que estão disponíveis no menu de contexto da lista de ficheiros. Para as operações críticas, como a remoção de ficheiros, aconselha-se que marque o <guilabel
>Confirmar</guilabel
> para apresentar uma janela de confirmação antes de executar o comando. O <guilabel
>Resultado</guilabel
> pode ficar marcado para ver o resultado escrito pelos comandos da consola (no 'standard output' e 'standard error'). O <guilabel
>Nome</guilabel
> é o nome apresentado no menu de contexto. O <guilabel
>Comando</guilabel
> é a linha de comandos a executar. Os argumentos podem ser passados com os seguintes códigos: </para>

<itemizedlist>
<listitem
><para
>%F %{files} Localizações dos ficheiros (uma lista se estiverem vários ficheiros seleccionados)</para
></listitem>
<listitem
><para
>%f %{file} Localização de um único ficheiro individual</para
></listitem>
<listitem
><para
>%uF %{urls} &URL;s (uma lista se estiverem vários ficheiros seleccionados)</para
></listitem>
<listitem
><para
>%uf %{url} &URL; de um único ficheiro individual</para
></listitem>
<listitem
><para
>%d %{directory} Pasta</para
></listitem>
<listitem
><para
>%s %{title} Título (Música)</para
></listitem>
<listitem
><para
>%a %{artist} Artista</para
></listitem>
<listitem
><para
>%l %{album} Álbum</para
></listitem>
<listitem
><para
>%c %{comment} Comentário</para
></listitem>
<listitem
><para
>%y %{year} Ano</para
></listitem>
<listitem
><para
>%t %{track} Faixa (<abbrev
>p.ex.</abbrev
> 01)</para
></listitem>
<listitem
><para
>%t %{track.n} Faixa com o tamanho do campo 'n' (<abbrev
>p.ex.</abbrev
> 001 para %{track.3})</para
></listitem>
<listitem
><para
>%T %{tracknumber} Faixa (sem os zeros iniciais, <abbrev
>p.ex.</abbrev
> 1)</para
></listitem>
<listitem
><para
>%g %{genre} Género</para
></listitem>
<listitem
><para
>%b %{browser} Comando para iniciar o navegador Web</para
></listitem>
<listitem
><para
>%q %{qmlpath} Pasta de base dos ficheiros QML fornecidos</para
></listitem>
</itemizedlist>

<para
>O código especial <command
>@separator</command
> pode ser configurado como um comando para inserir um separador no menu de contexto das acções do utilizador. Poderá colocar os itens de menu num submenu se os rodear com comandos <command
>@beginmenu</command
> e <command
>@endmenu</command
>. O nome do submenu é determinado pela coluna <guilabel
>Nome</guilabel
> do comando <command
>@beginmenu</command
>. </para>

<para id="configure-user-actions-qml"
>Para executar os programas em QML, o <command
>@qml</command
> é usado como um nome de comando. A localização do programa em QML é passada como um parâmetro. Os programas existentes poderão ser encontrados na pasta <filename
>%{qmlpath}/script/</filename
> (no &Linux; é tipicamente a <filename
>/usr/share/kid3/qml/script/</filename
>, no Windows a <filename
>qml/script/</filename
> dentro da pasta de instalação e no &macOS; na pasta da aplicação <filename
>kid3.app/Contents/Resources/qml/script/</filename
>). Poderá guardar os programas personalizados em qualquer pasta. Se o código QML usar componentes &GUI;, o <command
>@qmlview</command
> deverá ser usado em vez do <command
>@qml</command
>. Os parâmetros adicionais são passados ao programa em QML, onde ficarão disponíveis através da função <function
>getArguments()</function
>. Poderá ter uma visão geral de algumas funções e propriedades que estão disponíveis no apêndice da <link linkend="qml-interface"
>Interface de QML</link
>. </para>

<para
>O comando que será introduzido com o %{browser} pode ser definido no campo de texto <guilabel
>Navegador Web</guilabel
> acima. Os comandos que comecem por %{browser} podem ser usados para obter informações acerca dos ficheiros de áudio na Web; por exemplo <screen width="40">
<userinput
>%{browser} http://lyricwiki.org/%u{artist}:%u{title}</userinput>
</screen
> irá pesquisar pelas letras da música actual no <ulink url="http://www.lyricwiki.org"
>LyricWiki</ulink
>. O "u" em %u{artist} e %u{title} é usado para codificar como &URL; os dados do artista %{artist} e da música %{title}. É fácil definir as suas próprias pesquisas da mesma forma, <abbrev
>p.ex.</abbrev
> uma pesquisa por imagens no <ulink url="http://www.google.com"
>Google</ulink
>: <screen width="40"
><userinput
>%{browser} http://images.google.com/images?q=%u{artist}%20%u{album}</userinput
>
</screen>
</para>
<para
>Para adicionar as imagens das capas dos álbuns à marca 2, poderá procurar por imagens no Google ou na Amazon com os comandos descritos acima. A imagem poderá ser adicionada à marca por arrastamento. Também poderá adicionar uma imagem com o botão <guibutton
>Adicionar</guibutton
>, seleccionando depois o pacote da Imagem e importar um ficheiro de imagem ou colá-lo a partir da área de transferência. Os pacotes de imagens são suportados nas marcas de ID3v2, MP4, FLAC, Ogg e ASF. </para>
<para
>Para adicionar e remover itens da tabela, poderá usar um menu de contexto. </para>
<para
>A página <guilabel
>Rede</guilabel
> contém apenas um campo para inserir o endereço do 'proxy' e, opcionalmente, o porto separados por dois-pontos. O 'proxy' será usado ao importar os dados a partir de um servidor na Internet quando a opção estiver assinalada. </para>
<para
>Na página de <guilabel
>Plugins</guilabel
>, poderá activar ou desactivar os 'plugins' disponíveis. Os mesmos estão separados em duas secções. A lista <guilabel
>'Plugins' de Meta-Dados &amp; Prioridade</guilabel
> contém os 'plugins' que suportam os formatos de ficheiros de áudio. A ordem dos 'plugins' é importante porque são avaliados de cima para baixo. Alguns dos formatos são suportados por vários 'plugins', pelo que os ficheiros serão abertos com o primeiro 'plugin' com suporte para os mesmos. O <guilabel
>TaglibMetadata</guilabel
> tem suporte para a maioria dos formatos, sendo que irá abrir a maior parte dos ficheiros, caso esteja no topo da lista. Se quiser usar um 'plugin' diferente para um formato de ficheiros, certifique-se que aparece antes do 'plugin' <guilabel
>TaglibMetadata</guilabel
>. Os detalhes sobre os 'plugins' de meta-dados, bem como o motivo pelo qual os poderá querer usar em vez da TagLib, estão enumerados em baixo. </para>
<itemizedlist>
<listitem
><para
><guilabel
>Id3libMetadata</guilabel
>: Usa o <ulink url="http://id3lib.sourceforge.net"
>id3lib</ulink
> para as marcas ID3v1.1 e ID3v2.3 nos ficheiros MP3, MP2, AAC. Suporta mais alguns tipos de pacotes que a TagLib.</para
></listitem>
<listitem
><para
><guilabel
>OggFlacMetadata</guilabel
>: Usa a <ulink url="http://xiph.org/ogg/"
>libogg</ulink
>, a <ulink url="http://xiph.org/vorbis/"
>libvorbis, libvorbisfile</ulink
> para os ficheiros Ogg e adicionalmente a <ulink url="http://flac.sourceforge.net"
>libFLAC++ e a libFLAC</ulink
> para os ficheiros FLAC. Estas são as bibliotecas oficiais para estes formatos.</para
></listitem>
<listitem
><para
><guilabel
>TaglibMetadata</guilabel
>: Usa a <ulink url="http://taglib.github.io/"
>TagLib</ulink
> que suporta um conjunto de formatos de ficheiros de áudio. Pode ser usado para todos os ficheiros de áudio suportados pelo &kid3;.</para
></listitem>
<listitem
><para
><guilabel
>Mp4v2Metadata</guilabel
>: o <ulink url="http://code.google.com/p/mp4v2"
>mp4v2</ulink
> foi usado originalmente pelo &kid3; para suportar os ficheiros M4A. Pode ser usado em caso de problemas com o suporte de M4A na TagLib. </para
></listitem>
</itemizedlist>
<para
>A secção de <guilabel
>'Plugins' Disponíveis</guilabel
> apresenta os restantes 'plugins'. A sua ordem não é relevante, mas poderão ser activados ou desactivados com as opções de marcação. </para>
<itemizedlist>
<listitem
><para
><guilabel
>AmazonImport</guilabel
>: Usado na função <guimenuitem
>Importar da Amazon...</guimenuitem
>. </para
></listitem>
<listitem
><para
><guilabel
>DiscogsImport</guilabel
>: Usado na função <guimenuitem
>Importar da Discogs...</guimenuitem
>. </para
></listitem>
<listitem
><para
><guilabel
>FreedbImport</guilabel
>: Usado na função <guimenuitem
>Importar da gnudb.org...</guimenuitem
>. </para
></listitem>
<listitem
><para
><guilabel
>MusicBrainzImport</guilabel
>: Usado na função <guimenuitem
>Importar da Versão do MusicBrainz...</guimenuitem
>. </para
></listitem>
<listitem
><para
><guilabel
>AcoustidImport</guilabel
>: Usado para a função <guimenuitem
>Importar da Impressão Digital do MusicBrainz...</guimenuitem
>. que depende das bibliotecas <ulink url="http://acoustid.org/chromaprint"
>Chromaprint</ulink
> e <ulink url="http://libav.org/"
>libav</ulink
>. </para
></listitem>
</itemizedlist>
<para
>Os 'plugins' que estiverem desactivados não serão carregados. Isto poderá ser usado para optimizar a utilização dos recursos e o tempo de arranque. A configuração nesta página só fará efeito após reiniciar o &kid3;. </para>
</listitem>
</varlistentry>

</variablelist>
</para>

</sect1>

<sect1 id="help-menu">
<title
>O Menu Ajuda</title>
<para>
<variablelist>

<varlistentry>
<term
><menuchoice
><guimenu
>Ajuda</guimenu
> <guimenuitem
>Manual do &kid3;</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Abre este manual.</action
></para
></listitem>
</varlistentry>

<varlistentry>
<term
><menuchoice
><guimenu
>Ajuda</guimenu
> <guimenuitem
>Acerca do &kid3;</guimenuitem
> </menuchoice
></term>
<listitem
><para
><action
>Mostra uma breve informação sobre o &kid3;. </action
></para
></listitem>
</varlistentry>


</variablelist>
</para>

</sect1>

</chapter>

<chapter id="kid3-cli">
<title
>kid3-cli</title>
<sect1 id="kid3-cli-commands">
<title
>Comandos</title>
<para
>O <command
>kid3-cli</command
> oferece uma interface de linha de comandos para o &kid3;. Se for usada a localização de uma pasta, a mesma será aberta. Se forem indicadas as localizações de um ou mais ficheiros, será aberta a pasta comum com os ficheiros seleccionados. Os comandos subsequentes irão então funcionar sobre esses ficheiros. Os comandos são indicados através das opções <option
>-c</option
>. Se forem passados vários comandos, os mesmos serão executados pela ordem indicada. Se os ficheiros forem modificados pelos comandos, eles serão gravados no fim. Se não forem passadas opções de comandos, o <command
>kid3-cli</command
> inicia no modo interactivo. Os comandos poderão então ser introduzidos e irão funcionar sobre a selecção actual. As seguintes secções apresentam todos os comandos disponíveis. </para>

<sect2 id="cli-help">
<title
>Ajuda</title>
<cmdsynopsis
><command
>help</command
> <arg
><replaceable
>NOME-COMANDO</replaceable
></arg
> </cmdsynopsis>
<para
>Mostra ajuda sobre os parâmetros do <replaceable
>NOME-COMANDO</replaceable
> ou sobre todos os comandos, caso não seja indicado nenhum nome de comando. </para>
</sect2>

<sect2 id="cli-timeout">
<title
>Tempo-limite</title>
<cmdsynopsis
><command
>timeout</command
> <group
> <arg choice="plain"
>default</arg
> <arg choice="plain"
>off</arg
> <arg choice="plain"
><replaceable
>TEMPO</replaceable
></arg
> </group
> </cmdsynopsis>
<para
>Substitui o tempo-limite predefinido dos comandos. Os comandos da CLI são interrompidos após ser ultrapassado um dado tempo-limite para os comandos. Este tempo-limite é de 10 segundos para o <command
>ls</command
> e o <command
>albumart</command
>, de 60 segundos para o <command
>autoimport</command
> e <command
>filter</command
> e de 3 segundos para todos os outros comandos. Se tiver de processar um número enorme de ficheiros, estes tempos-limites podem ser demasiado restritos; como tal, poderá definir o tempo-limite para todos os comandos como sendo <replaceable
>TEMPO</replaceable
> ms, desligado por completo ou deixar com os valores predefinidos. </para>
</sect2>

<sect2 id="cli-exit">
<title
>Sair da aplicação</title>
<cmdsynopsis
><command
>exit</command
> <arg
>force</arg
> </cmdsynopsis>
<para
>Sai da aplicação. Se existirem ficheiros por gravar modificados, o parâmetro <parameter class="command"
>force</parameter
> é obrigatório. </para>
</sect2>

<sect2 id="cli-cd">
<title
>Mudar de pasta</title>
<cmdsynopsis
><command
>cd</command
> <arg
><replaceable
>PASTA</replaceable
></arg
> </cmdsynopsis>
<para
>Se não for indicada nenhuma <replaceable
>PASTA</replaceable
>, muda para a pasta pessoal. Se for indicada uma pasta, muda para dentro dessa pasta. Se forem indicadas uma ou mais localizações de ficheiros, muda para a pasta comum entre elas e selecciona os ficheiros. </para>
</sect2>

<sect2 id="cli-pwd">
<title
>Imprime o nome da pasta actual</title>
<cmdsynopsis>
<command
>pwd</command>
</cmdsynopsis>
<para
>Imprime o nome da pasta de trabalho actual.</para>
</sect2>

<sect2 id="cli-ls">
<title
>Lista de pastas</title>
<cmdsynopsis>
<command
>ls</command>
</cmdsynopsis>
<para
>Apresenta o conteúdo da pasta actual. Isto corresponde à lista de ficheiros na &GUI; do &kid3;. Cinco caracteres antes dos nomes dos ficheiros mostram o estado do ficheiro. </para>

<itemizedlist>
<listitem
><para
><computeroutput
>&gt;</computeroutput
> O ficheiro está seleccionado. </para
></listitem>
<listitem
><para
><computeroutput
>*</computeroutput
> O ficheiro está modificado. </para
></listitem>
<listitem
><para
><computeroutput
>1</computeroutput
> O ficheiro tem uma marca 1, caso contrário aparece '<computeroutput
>-</computeroutput
>'.</para
></listitem>
<listitem
><para
><computeroutput
>2</computeroutput
> O ficheiro tem uma marca 2, caso contrário aparece '<computeroutput
>-</computeroutput
>'.</para
></listitem>
<listitem
><para
><computeroutput
>3</computeroutput
> O ficheiro tem uma marca 3, caso contrário aparece '<computeroutput
>-</computeroutput
>'.</para
></listitem>
</itemizedlist>

<screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>ls</userinput
><computeroutput>
  1-- 01 Intro.mp3

> 12- 02 So Temos Este.mp3
 *1-- 03 Final.mp3</computeroutput
></screen>

<para
>Neste exemplo, todos os ficheiros têm uma marca 1, enquanto o segundo ficheiro também tem uma marca 2 e a mesma está seleccionada. O terceiro ficheiro está modificado. </para>
</sect2>

<sect2 id="cli-save">
<title
>Gravar os ficheiros alterados</title>
<cmdsynopsis>
<command
>save</command>
</cmdsynopsis>
 
</sect2>

<sect2 id="cli-select">
<title
>Seleccionar o ficheiro</title>
<cmdsynopsis
><command
>select</command
> <group
> <arg choice="plain"
>all</arg
> <arg choice="plain"
>none</arg
> <arg choice="plain"
>first</arg
> <arg choice="plain"
>previous</arg
> <arg choice="plain"
>next</arg
> <arg choice="plain" rep="repeat"
><replaceable
>FICHEIRO</replaceable
></arg
> </group
> </cmdsynopsis>
<para
>Para seleccionar todos os ficheiros, introduza <userinput
>select all</userinput
>; para deseleccionar todos os ficheiros, indique <userinput
>select none</userinput
>. Para percorrer os ficheiros na pasta actual, comece com o <userinput
>select first</userinput
> e vá avançando com o <userinput
>select next</userinput
> ou recuando com o <userinput
>select previous</userinput
>. Poderá adicionar ficheiros específicos à selecção actual, indicando para tal os seus nomes. São permitidas sequências especiais; como tal, o <userinput
>select *.mp3</userinput
> irá seleccionar todos os ficheiros MP3 na pasta actual. </para>

<screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>select first</userinput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>ls</userinput
><computeroutput>

> 1-- 01 Intro.mp3
  12- 02 So Temos Este.mp3
 *1-- 03 Final.mp3</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>select next</userinput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>ls</userinput
><computeroutput>
  1-- 01 Intro.mp3

> 12- 02 So Temos Este.mp3
 *1-- 03 Final.mp3</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>select *.mp3</userinput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>ls</userinput
><computeroutput>

> 1-- 01 Intro.mp3

> 12- 02 So Temos Este.mp3

>*1-- 03 Final.mp3</computeroutput
></screen>
</sect2>

<sect2 id="cli-tag">
<title
>Seleccionar a marca</title>
<cmdsynopsis
><command
>tag</command
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Muitos dos comandos têm um parâmetro opcional <replaceable
>NÚMEROS-MARCAS</replaceable
>, que define se o comando funciona na marca 1, 2 ou 3. Se este parâmetro for omitido, serão usados os números de marcas predefinidos, os quais poderão ser definidos por este comando. No arranque está configurado como <literal
>12</literal
>, o que significa que a informação é lida da marca 2, se disponível, caso contrário da marca 1; as modificações são efectuadas na marca 2. O parâmetro <option
><replaceable
>NÚMEROS-MARCAS</replaceable
></option
> poderá ser configurado como <userinput
>1</userinput
>, <userinput
>2</userinput
> ou <userinput
>3</userinput
> para funcionar apenas na marca correspondente. Se o parâmetro for omitido, é apresentado o valor actual. </para>
</sect2>

<sect2 id="cli-get">
<title
>Obter os dados da marca</title>
<cmdsynopsis
><command
>get</command
> <group
> <arg choice="plain"
>all</arg
> <arg choice="plain"
><replaceable
>NOME-PACOTE</replaceable
></arg
> </group
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Este comando pode ser usado para ler o valor de um dado pacote de marcas ou para obter informações sobre todos os pacotes de marcas (se o argumento for omitido ou for usado o <option
>all</option
>). Os pacotes modificados estão marcados com um '<computeroutput
>*</computeroutput
>'. </para>

<screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>get</userinput
><computeroutput>
Ficheiro: MPEG 1 Layer 3 192 kbps 44100 Hz Joint Stereo
  Name: 01 Intro.mp3
Marca 1: ID3v1.1
  Título        Intro
  Artista       Famoso Desconhecido
  Álbum         Vamos Marcar
  Date          2013
  Track Number  1
  Genre         Pop</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>get title</userinput
><computeroutput>
Intro</computeroutput
></screen>
<para
>Para gravar o conteúdo de uma marca de imagem para um ficheiro, use <screen width="65"
><userinput
>get picture:'/local/da/pasta.jpg'</userinput
></screen>
</para>
<para
>Para gravar as letras sincronizadas para um ficheiro LRC, use <screen width="65"
><userinput
>get SYLT:'/local/das/letras.lrc'</userinput
></screen>
</para>
<para
>É possível obter apenas um campo específico de um pacote, como por exemplo <userinput
>get POPM.Email</userinput
> para o campo de E-Mail de um pacote de Medição de Popularidade. Se um ficheiro tiver vários pacotes do mesmo tipo, poderá indexar os diferentes pacotes com parêntesis rectos; por exemplo, o primeiro artista de um comentário de Vorbis poderá ser obtido com a expressão <userinput
>get performer[0]</userinput
> e o segundo com <userinput
>get performer[1]</userinput
>. </para>
<para
>O pseudo-nome de campo "selected" pode ser usado para verificar se um dado pacote está seleccionado, por exemplo <userinput
>get artist.selected</userinput
> irá devolver <computeroutput
>1</computeroutput
> se o pacote do artista estiver seleccionado, caso contrário devolve <computeroutput
>0</computeroutput
>. </para>
</sect2>

<sect2 id="cli-set">
<title
>Modificar os dados da marca</title>
<cmdsynopsis
><command
>set</command
> <arg choice="req"
><replaceable
>NOME-PACOTE</replaceable
></arg
> <arg choice="req"
><replaceable
>VALOR-PACOTE</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Este comando configura o valor de um dado pacote de marca em específico. Se o <replaceable
>VALOR-PACOTE</replaceable
> estiver vazio, o pacote é apagado. </para>
<screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>set remixer 'Fam. Desconhecido'</userinput
></screen>
<para
>Para configurar o conteúdo de um pacote de imagem a partir de um ficheiro, use <screen width="65"
><userinput
>set picture:'/local/da/pasta.jpg' 'Descrição da Imagem'</userinput
></screen>
</para>
<para
>Para configurar as letras sincronizadas a partir de um ficheiro LRC, use <screen width="65"
><userinput
>set SYLT:'/local/das/letras.lrc' 'Descrição das Letras'</userinput
></screen>
</para>
<para
>Para configurar um dado campo específico de um pacote, o nome do campo pode ser definido a seguir a um ponto, <abbrev
>p.ex.</abbrev
> para configurar o campo Contador de um pacote Medição de Popularidade, use <screen width="65"
><userinput
>set POPM.Counter 5</userinput
></screen>
</para>
<para
>Uma aplicação para as definições dos campos é o caso em que deseja usar um pacote TXXX personalizado com a descrição da "classificação" em vez de um pacote de Medição de Popularidade (isso parece ser o caso usado por alguns 'plugins'). Poderá criar um desses pacotes de classificação TXXX com o <command
>kid3-cli</command
>; contudo, terá primeiro de criar um pacote TXXX com a descrição "rating" e depois configurar o valor deste pacote com o valor da classificação. <screen width="65">
<prompt
>kid3-cli&gt; </prompt
><userinput
>set rating ""</userinput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>set TXXX.Description rating</userinput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>set rating 5</userinput>
</screen
> O primeiro comando irá apagar um pacote POPM existente, porque se existir um desses pacotes o <userinput
>set rating 5</userinput
> iria configurar o pacote POPM e não o pacote TXXX. Outra possibilidade seria usar o <userinput
>set TXXX.Text 5</userinput
>, mas só iria funcionar se não estivesse presente nenhum outro pacote TXXX. </para>
<para
>Para configurar vários pacotes do mesmo tipo, poderá indicar um índice entre parêntesis, <abbrev
>p.ex.</abbrev
> para definir vários artistas num comentário de Vorbis, use <screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>set performer[0] 'Liza don Getti (soprano)'</userinput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>set performer[1] 'Joe Barr (piano)'</userinput
>
</screen>
</para>
<para
>Para seleccionar certos pacotes antes de uma operação para copiar, colar ou remover, o nome do pseudo-campo "selected" pode ser usado. Normalmente, todos os pacotes estão seleccionados; para deseleccionar tudo, use o comando <userinput
>set '*.selected' 0</userinput
> e depois por exemplo <userinput
>set artist.selected 1</userinput
> para seleccionar o pacote do artista. </para>
</sect2>

<sect2 id="cli-revert">
<title
>Reverter</title>
<cmdsynopsis>
<command
>revert</command>
</cmdsynopsis>
<para
>Reverte todas as modificações nos ficheiros seleccionados (ou todos os ficheiros se não estiver nenhum seleccionado). </para>
</sect2>

<sect2 id="cli-import">
<title
>Importar de ficheiro</title>
<cmdsynopsis
><command
>import</command
> <arg choice="req"
><replaceable
>FICHEIRO</replaceable
></arg
> <arg choice="req"
><replaceable
>NOME-FORMATO</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>As marcas são importadas a partir do ficheiro <replaceable
>FICHEIRO</replaceable
> no formato com o nome <replaceable
>NOME-FORMATO</replaceable
> (<abbrev
>p.ex.</abbrev
> <userinput
>"CSV sem aspas"</userinput
>, veja como <link linkend="import-text"
>Importar</link
>). </para>
<para
>Se for usado o <userinput
>tags</userinput
> para o <replaceable
>FICHEIRO</replaceable
>, as marcas são importadas a partir das outras marcas. Em vez dos parâmetros <replaceable
>NOME-FORMATO</replaceable
>, são obrigatórios a <replaceable
>ORIGEM</replaceable
> e a <replaceable
>EXTRACÇÃO</replaceable
>; veja mais em <link linkend="import-tags"
>Importar a Partir das Marcas</link
>. Para aplicar a importação a partir das marcas nos ficheiros seleccionados, use o <userinput
>tagsel</userinput
> em vez do <userinput
>tags</userinput
>. Esta função também suporta o resultado do valor extraído, usando uma <replaceable
>EXTRACÇÃO</replaceable
> com o valor <userinput
>%{__return}(.+)</userinput
>. </para>
</sect2>

<sect2 id="cli-autoimport">
<title
>Importação automática</title>
<cmdsynopsis
><command
>autoimport</command
> <arg
><replaceable
>NOME-PERFIL</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Faz uma importação em lote, usando para tal o perfil <replaceable
>NOME-PERFIL</replaceable
> (veja a <link linkend="batch-import"
>Importação Automática</link
>, <userinput
>"Tudo"</userinput
> é usado por omissão). </para>
</sect2>

<sect2 id="cli-albumart">
<title
>Obter as imagens da capa do álbum</title>
<cmdsynopsis
><command
>albumart</command
> <arg choice="req"
><replaceable
>URL</replaceable
></arg
> <arg
>all</arg
> </cmdsynopsis>
<para
>Configura as imagens do álbum, transferindo uma imagem a partir do <replaceable
>URL</replaceable
>. As regras definidas na janela para <link linkend="browse_pictures"
>Escolher as Imagens das Capas</link
> são usadas para transformar os &URL;'s gerais (<abbrev
>p.ex.</abbrev
> da Amazon) num &URL; de imagem. Para configurar a capa do álbum para um ficheiro de imagem local, use o comando <link linkend="cli-set"
>set</link
>. </para>
<screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>albumart
http://www.amazon.com/Versus-World-Amon-Amarth/dp/B000078DOC</userinput
></screen>
</sect2>

<sect2 id="cli-export">
<title
>Exportar para um ficheiro</title>
<cmdsynopsis
><command
>export</command
> <arg choice="req"
><replaceable
>FICHEIRO</replaceable
></arg
> <arg choice="req"
><replaceable
>NOME-FORMATO</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>As marcas são exportadas para o ficheiro <replaceable
>FICHEIRO</replaceable
> no formato com o nome <replaceable
>NOME-FORMATO</replaceable
> (<abbrev
>p.ex.</abbrev
> <userinput
>"CSV sem aspas"</userinput
>, ver como <link linkend="export"
>Exportar</link
>). </para>
</sect2>

<sect2 id="cli-playlist">
<title
>Criar a lista de reprodução</title>
<cmdsynopsis>
<command
>playlist</command>
</cmdsynopsis>
<para
>Cria uma lista de reprodução no formato definido na configuração; veja como <link linkend="create-playlist"
>Criar uma Lista de Reprodução</link
>. </para>
</sect2>

<sect2 id="cli-filenameformat">
<title
>Aplicar o formato de nomes dos ficheiros</title>
<cmdsynopsis>
<command
>filenameformat</command>
</cmdsynopsis>
<para
>Aplica o formato de nomes de ficheiros definido na configuração; veja como <link linkend="apply-filename-format"
>Aplicar o Formato de Nomes de Ficheiros</link
>. </para>
</sect2>

<sect2 id="cli-tagformat">
<title
>Aplicar o formato das marcas</title>
<cmdsynopsis>
<command
>tagformat</command>
</cmdsynopsis>
<para
>Aplica o formato de marcas definido na configuração; veja como <link linkend="apply-tag-format"
>Aplicar o Formato de Marcas</link
>. </para>
</sect2>

<sect2 id="cli-textencoding">
<title
>Aplicar a codificação do texto</title>
<cmdsynopsis>
<command
>textencoding</command>
</cmdsynopsis>
<para
>Aplica a codificação de texto definida na configuração; veja como <link linkend="apply-text-encoding"
>Aplicar a Codificação do Texto</link
>. </para>
</sect2>

<sect2 id="cli-renamedir">
<title
>Mudar o nome da pasta</title>
<cmdsynopsis
><command
>renamedir</command
> <arg
><replaceable
>FORMATO</replaceable
></arg
> <group
> <arg choice="plain"
>create</arg
> <arg choice="plain"
>rename</arg
> <arg choice="plain"
>dryrun</arg
> </group
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Muda o nome ou cria pastas a partir dos valores nas marcas, de acordo com um dado <replaceable
>FORMATO</replaceable
> (<abbrev
>p.ex.</abbrev
> <userinput
>%{artist} - %{album}</userinput
>; veja mais em <link linkend="rename-directory"
>Mudar o Nome da Pasta</link
>); se não for indicado nenhum formato, é usado o formato definido na janela para <guilabel
>Mudar o nome da pasta</guilabel
>. O modo predefinido é <option
>rename</option
>; para criar pastas, deverá ser indicado de forma explícita o <option
>create</option
>. As acções de mudança de nome serão efectuadas de imediato. Para ver o que irá ser feito, use a opção <option
>dryrun</option
>. </para>
</sect2>

<sect2 id="cli-numbertracks">
<title
>Numerar as faixas</title>
<cmdsynopsis
><command
>numbertracks</command
> <arg
><replaceable
>NÚMERO-FAIXA</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Numera as faixas seleccionadas a começar em <replaceable
>NÚMERO-FAIXA</replaceable
> (<literal
>1</literal
> por omissão). </para>
</sect2>

<sect2 id="cli-filter">
<title
>Filtro</title>
<cmdsynopsis
><command
>filter</command
> <group
> <arg choice="plain"
><replaceable
>NOME-FILTRO</replaceable
></arg
> <arg choice="plain"
><replaceable
>FORMATO-FILTRO</replaceable
></arg
> </group
> </cmdsynopsis>
<para
>Filtra os ficheiros de forma que apenas os ficheiros correspondentes ao <replaceable
>FORMATO-FILTRO</replaceable
> fiquem visíveis. O nome de uma expressão de filtro predefinida (<abbrev
>p.ex.</abbrev
> <userinput
>"Falta de Correspondência Entre Nomes de Ficheiros e Marcas"</userinput
>) pode ser usado em vez de uma expressão de filtro; veja o <link linkend="filter"
>Filtro</link
>. </para>

<screen width="65"
><prompt
>kid3-cli&gt; </prompt
><userinput
>filter '%{title} contains "tro"'</userinput
><computeroutput>
Iniciado
  /home/utilizador/Famoso Desconhecido - Vamos Marcar
+ 01 Intro.mp3
- 02 So Temos Este.mp3
+ 03 Final.mp3
Terminado</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>ls</userinput
><computeroutput>
  1-- 01 Intro.mp3
  1-- 03 Final.mp3</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>filter All</userinput
><computeroutput>
Iniciado
  /home/utilizador/Famoso Desconhecido - Vamos Marcar
+ 01 Intro.mp3
+ 02 So Temos Este.mp3
+ 03 Final.mp3
Terminado</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>ls</userinput
><computeroutput>
  1-- 01 Intro.mp3
  12- 02 So Temos Este.mp3
  1-- 03 Final.mp3</computeroutput
></screen>
</sect2>

<sect2 id="cli-to24">
<title
>Converter o ID3v2.3 para ID3v2.4</title>
<cmdsynopsis>
<command
>to24</command>
</cmdsynopsis>
</sect2>

<sect2 id="cli-to23">
<title
>Converter o ID3v2.4 para ID3v2.3</title>
<cmdsynopsis>
<command
>to23</command>
</cmdsynopsis>
</sect2>

<sect2 id="cli-fromtag">
<title
>Nome do ficheiro a partir da marca</title>
<cmdsynopsis
><command
>fromtag</command
> <arg
><replaceable
>FORMATO</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>Configura os nomes dos ficheiros seleccionados a partir dos valores nas marcas; por exemplo <userinput
>fromtag '%{track} - %{title}' 1</userinput
>. Se não for indicado nenhum formato, será usado o formato definido na &GUI;. </para>
</sect2>

<sect2 id="cli-totag">
<title
>Marca a partir do nome do ficheiro</title>
<cmdsynopsis
><command
>totag</command
> <arg
><replaceable
>FORMATO</replaceable
></arg
> <arg
><replaceable
>NÚMEROS-MARCAS</replaceable
></arg
> </cmdsynopsis>
<para
>É usada uma segunda lista <guilabel
>Formato</guilabel
> (com uma seta para baixo) para gerar as marcas a partir do nome do ficheiro. Se o formato do nome do ficheiro não corresponder a este padrão definido na &GUI;, serão testados alguns outros formatos usados de forma comum. </para>
</sect2>

<sect2 id="cli-syncto">
<title
>Marca para outra marca</title>
<cmdsynopsis
><command
>syncto</command
> <arg choice="req"
><replaceable
>NÚMERO-MARCA</replaceable
></arg
> </cmdsynopsis>
<para
>Copia os pacotes de marcas de uma marca para a outra; <abbrev
>p.ex.</abbrev
> para configurar a marca ID3v2 a partir da marca ID3v1, use o <userinput
>syncto 2</userinput
>. </para>
</sect2>

<sect2 id="cli-copy">
<title
>Copiar</title>
<cmdsynopsis
><command
>copy</command
> <arg
><replaceable
>NÚMERO-MARCA</replaceable
></arg
> </cmdsynopsis>
<para
>Copia os pacotes de marcas do ficheiro seleccionado para a área de cópia interna. Eles poderão ser configurados noutro ficheiro, usando o comando <command
>paste</command
>. </para>
<para
>Para copiar apenas um sub-conjunto dos pacotes, use o pseudo-campo "selected" com o comando <command
>set</command
>. Por exemplo, para copiar apenas o número do disco e os direitos de cópia, use <screen width="65"
><userinput
>set '*.selected' 0</userinput>
<userinput
>set discnumber.selected 1</userinput>
<userinput
>set copyright.selected 1</userinput>
<userinput
>copy</userinput
>
</screen>
</para>
</sect2>

<sect2 id="cli-paste">
<title
>Colar</title>
<cmdsynopsis
><command
>paste</command
> <arg
><replaceable
>NÚMERO-MARCA</replaceable
></arg
> </cmdsynopsis>
<para
>Configura os pacotes de marcas a partir do conteúdo da área do comando <command
>copy</command
> sobre os ficheiros seleccionados. </para>
</sect2>

<sect2 id="cli-remove">
<title
>Remover</title>
<cmdsynopsis
><command
>remove</command
> <arg
><replaceable
>NÚMERO-MARCA</replaceable
></arg
> </cmdsynopsis>
<para
>Remove uma marca. </para>
<para
>É possível remover apenas um sub-conjunto dos pacotes se os seleccionar como descrito no <link linkend="cli-copy"
>comando <command
>copy</command
></link
>. </para>
</sect2>

<sect2 id="cli-config">
<title
>Configurar o Kid3</title>
<cmdsynopsis
><command
>config</command
> <arg
><replaceable
>OPÇÃO</replaceable
></arg
> <arg
><replaceable
>VALOR</replaceable
></arg
> </cmdsynopsis>
<para
>Consulta ou modifica uma opção de configuração. </para>
<para
>Uma <replaceable
>OPÇÃO</replaceable
> consiste no nome de um grupo e de uma propriedade, separados por um ponto. Quando não for indicada nenhuma <replaceable
>OPÇÃO</replaceable
>, aparecem todos os grupos disponíveis. Para um dado grupo e propriedade, aparece o valor configurado de momento. Para mudar a configuração, o novo valor pode ser passado como segundo argumento. </para>
<para
>Se o valor de uma dada opção for uma lista, todos os elementos da lista têm de ser indicados como argumentos. Isto significa que, para adicionar um elemento a uma lista de elementos existente, todos os elementos existentes terão de ser passados seguidos pelo novo elemento. Nessa situação, é mais fácil usar o modo JSON, onde a lista actual poderá ser copiada com o novo elemento adicionado. </para>
</sect2>

</sect1>

<sect1 id="kid3-cli-examples">
<title
>Exemplos</title>
<para
>Configura o título contendo um apóstrofo. Os comandos passados ao <command
>kid3-cli</command
> com o <parameter
>-c</parameter
> têm de estar entre aspas se não consistirem apenas numa única palavra. Se um destes comandos tiver ele próprio um argumento com espaços, esse argumento também terá de estar entre aspas. Nas consolas de &UNIX;, poderá usar plicas ou aspas, mas na Linha de Comandos do Windows, é importante que as aspas exteriores sejam feitas com aspas e as interiores com plicas. Se o texto dentro das plicas tiverem uma plica, a mesma terá de ser escapada com uma barra invertida, como é demonstrado no seguinte exemplo:</para>
<screen width="65"
><userinput
>kid3-cli -c "set title 'I\'ll be there for you'" /local/da/pasta</userinput
></screen>

<para
>Configure a capa do álbum de todos os ficheiros de uma pasta com a função de importação em lote:</para>
<screen width="65"
><userinput
>kid3-cli -c "autoimport 'Cover Art'" /local/da/pasta</userinput
></screen>

<para
>Remover os pacotes de comentários e aplicar o formato da marca em ambas as marcas de todos os ficheiros MP3 de uma pasta:</para>
<screen width="65"
><userinput
>kid3-cli -c "set comment '' 1" -c "set comment '' 2" \
-c "tagformat 1" -c "tagformat 2" /local/da/pasta/*.mp3</userinput
></screen>

<para
>Importar automaticamente a marca 2, sincronizar com a marca 1, configura os nomes dos ficheiros a partir da marca 2 e finalmente criar uma lista de reprodução:</para>
<screen width="65"
><userinput
>kid3-cli -c autoimport -c "syncto 1" -c fromtag -c playlist \
  /local/da/pasta/*.mp3</userinput
></screen>

<para
>Para todos os ficheiros com uma marca ID3v2.4.0, converte para ID3v2.3.0 e remove o pacote do maestro:</para>
<screen width="65"
><userinput
>kid3-cli -c "filter 'ID3v2.4.0 Tag'" -c "select all" -c to23 \
  -c "set arranger ''" /local/da/pasta</userinput
></screen>

<para
>Este programa em Python usa o <command
>kid3-cli</command
> para gerar pacotes do iTunes Sound Check iTunNORM a partir dos dados de ganho da reprodução.</para>
<programlisting
><![CDATA[
#!/usr/bin/env python3
# Gerar o iTunes Sound Check a partir do Ganho de Reprodução.
import os, sys, subprocess

def rg2sc(dirpath):
  for raiz, pastas, ficheiros in os.walk(pasta):
    for nome in ficheiros:
      if nome.endswith(('.mp3', '.m4a', '.aiff', '.aif')):
        fn = os.path.join(raiz, nome)
        rg = subprocess.check_output([
          'kid3-cli', '-c', 'get "replaygain_track_gain"',
           fn]).strip()
        if rg.endswith(b' dB'):
          rg = rg[:-3]
        try:
          rg = float(rg)
        except ValueError:
          print('O valor %s de %s não é um número fraccionário' % (rg, fn))
          continue
        sc = (' ' + ('%08X' % int((10 ** (-rg / 10)) * 1000) )) * 10
        subprocess.call([
          'kid3-cli', '-c', 'set iTunNORM "%s"' % sc, fn])

if __name__ == '__main__':
  rg2sc(sys.argv[1])
]]>
</programlisting>
</sect1>

<sect1 id="kid3-cli-json">
<title
>Formato &JSON;</title>
<para
>Para facilitar o processamento dos resultados do <command
>kid3-cli</command
>, é possível obter o resultado no formato &JSON;. Quando o pedido vier no formato &JSON;, a resposta será também em &JSON;. Um formato compacto do pedido irá também dar uma representação compacta da resposta. Se o pedido tiver um campo "id", assume-se que é um pedido de &JSON;-RPC e a resposta irá devolver um campo "jsonrpc" e o "id" do pedido. O formato do pedido usa os mesmos comandos que a CLI normal, sendo que o campo "method" contém o comando e os parâmetros (se existirem) são fornecidos na lista "params". A resposta contém um objecto "result", que também poderá ser nulo se o comando <command
>kid3-cli</command
> correspondente não devolver um resultado. Em caso de erro, é devolvido um objecto "error" com os campos "code" e "message" usados da mesma forma que o  &JSON;-RPC. <screen width="80"
><prompt
>kid3-cli&gt; </prompt
><userinput
>{"method":"set","params":["artist","Um Artista"]}</userinput>
<computeroutput
>{"result":null}</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>{"method":"get","params":["artist",2]}</userinput>
<computeroutput
>{"result":"Um Artista"}</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>{"method": "get", "params": ["artist"]}</userinput>
<computeroutput
>{
    "result": "Um Artista"
}
</computeroutput>
<prompt
>kid3-cli&gt; </prompt
><userinput
>{"jsonrpc":"2.0","id":"123","method":"get","params":["artist"]}</userinput>
<computeroutput
>{"id":"123","jsonrpc":"2.0","result":"Um Artista"}</computeroutput
>
</screen>

</para>
</sect1>

</chapter>

<chapter id="credits">

<title
>Créditos e Licença</title>

<para
>&kid3; </para>
<para
>Programa criado por Urs Fleisch <email
>ufleisch@users.sourceforge.net</email
> </para>

<para
>Tradução de José Nuno Pires <email
>zepires@gmail.com</email
></para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Instalação</title>

<sect1 id="getting-kid3">
<title
>Como obter o &kid3;</title>

<para
>Poderá encontrar o &kid3; em <ulink url="https://kid3.kde.org"
>https://kid3.kde.org</ulink
>. </para>
</sect1>

<sect1 id="requirements">
<title
>Requisitos</title>

<para
>O &kid3; precisa do <ulink url="https://www.qt.io"
>&Qt;</ulink
>. O <ulink url="http://www.kde.org"
>&kde;</ulink
> é recomendado, mas não é necessário, dado que o &kid3; também pode ser compilado como uma aplicação do &Qt;. O &kid3; pode ser compilado nos sistemas onde essas bibliotecas estão disponíveis, <abbrev
>p.ex.</abbrev
> para o GNU/&Linux;, &Windows; e &macOS;. Para marcar os ficheiros Ogg/Vorbis, são necessárias as bibliotecas <ulink url="http://xiph.org/ogg/"
>libogg</ulink
>, <ulink url="http://xiph.org/vorbis/"
>libvorbis e libvorbisfile</ulink
>, para os ficheiros FLAC, são necessárias a <ulink url="http://flac.sourceforge.net"
>libFLAC++ e a libFLAC</ulink
>. A <ulink url="http://id3lib.sourceforge.net"
>id3lib</ulink
> é usada para os ficheiros MP3. Estes quatro formatos também são suportados pela <ulink url="http://taglib.github.io/"
>TagLib</ulink
>, que também consegue lidar com ficheiros Opus, MPC, APE, MP2, Speex, TrueAudio, WavPack, WMA, WAV, AIFF e módulos do Tracker. Para importar a partir de impressões-digitais acústicas, são usados o <ulink url="http://acoustid.org/chromaprint"
>Chromaprint</ulink
> e a <ulink url="http://libav.org/"
>libav</ulink
>. </para>
<para
>O &kid3; está disponível na maioria das distribuições de &Linux;, &Windows; e &macOS;. Poderá encontrar referências para o mesmo em <ulink url="https://kid3.kde.org"
> https://kid3.kde.org</ulink
>. </para>

</sect1>

<sect1 id="compilation">
<title
>Compilação e Instalação</title>

<para
>Poderá compilar o &kid3; com ou sem o &kde;. Sem o &kde;, o &kid3; é uma aplicação simples em &Qt; e poderá perder algumas funcionalidades de configuração e de sessões. </para>
<para
>Para uma versão para o &kde;, vá à pasta de topo e escreva <screen width="40"
><prompt
>%</prompt
> <userinput
>cmake .</userinput>
<prompt
>%</prompt
> <userinput
>make</userinput>
<prompt
>%</prompt
> <userinput
>make install</userinput
>
</screen>
</para>
<para
>Para compilar para diferentes versões do &Qt; ou do &kde;, defina as seguintes opções correspondentes ao <userinput
>cmake</userinput
>. </para>
<para
>Se nem todas as bibliotecas estiverem presentes, o &kid3; será compilado com funcionalidades reduzidas. Por isso, deverá ter o cuidado de ter todos os pacotes de desenvolvimento desejados instalados. Por outro lado, as opções do <userinput
>cmake</userinput
> controlam quais as bibliotecas que são compiladas. Por omissão, o valor é <userinput
>-DWITH_TAGLIB:BOOL=ON -DWITH_MP4V2:BOOL=OFF -DWITH_ID3LIB:BOOL=ON -DWITH_CHROMAPRINT:BOOL=ON -DWITH_VORBIS:BOOL=ON -DWITH_FLAC:BOOL=ON </userinput
>. Estas opções podem ser desactivas se usar o <userinput
>OFF</userinput
>. </para>
<para
>Para compilar o &kid3; como uma aplicação do &Qt; sem o &kde;, use a opção do <userinput
>cmake</userinput
> <userinput
>-DWITH_APPS=Qt</userinput
>. Para compilar tanto a versão para &kde; como para &Qt;, configure como <userinput
>-DWITH_APPS="Qt;KDE"</userinput
>. </para>
<para
>Para usar um a instalação específica do &Qt;, configure <userinput
>-DQT_QMAKE_EXECUTABLE=/local/do/qmake</userinput
>. </para>
<para
>A geração de pacotes RPM é suportada pelo ficheiro <filename
>kid3.spec</filename
>; para os pacotes da &Debian;, o programa <filename
>build-deb.sh</filename
> está disponível. </para>

<para
>A aplicação do &Qt; também pode ser compilada para o &Windows; e o &macOS;. O programa <filename
>buildlibs.sh</filename
> pode ser usado para obter e compilar todas as bibliotecas necessárias e criar um pacote do &kid3;. </para>

</sect1>

<sect1 id="configuration">
<title
>Configuração</title>

<para
>Com o &kde;, a configuração é gravada em <filename
>.config/kid3rc</filename
>. Como uma aplicação do &Qt;, este ficheiro encontra-se em <filename
>.config/Kid3/Kid3.conf</filename
>. No &Windows;, a configuração é guardada no Registry e no &macOS; é guardada num ficheiro 'plist'. </para>
<para
>A variável de ambiente <varname
>KID3_CONFIG_FILE</varname
> pode ser usada para definir a localização do ficheiro de configuração.</para>

</sect1>

</appendix>

<appendix id="dbus-interface">
<title
>A Interface de &DBus;</title>

<sect1 id="dbus-examples">
<title
>Exemplos de &DBus;</title>

<para
>No &Linux;, poderá usar uma interface do &DBus; para controlar o &kid3; através de programas. Os programas poderão ser criados em qualquer linguagem que tenha interfaces para o &DBus; (<abbrev
>p.ex.</abbrev
> em Python) e podem ser adicionadas às <guilabel
>Acções do Utilizador</guilabel
> para estender a funcionalidade do &kid3;. </para>

<para
>O artista na marca 2 do ficheiro actual poderá ser configurado com o valor "Famoso Desconhecido" com o seguinte código: </para>

<variablelist>
<varlistentry
><term
>Linha de comandos</term>
<listitem>
<programlisting
>dbus-send --dest=org.kde.kid3 --print-reply=literal \
/Kid3 org.kde.Kid3.setFrame int32:2 string:'Artist' \
string:'Famoso Desconhecido'
</programlisting>
<para
>ou ainda mais facilmente com o <command
>qdbus</command
> do &Qt; (o <command
>qdbusviewer</command
> pode ser usado para explorar a interface numa &GUI;): </para>
<programlisting
>qdbus org.kde.kid3 /Kid3 setFrame 2 Artist \
'Famoso Desconhecido'
</programlisting>
</listitem>
</varlistentry>
<varlistentry
><term
>Python</term>
<listitem>
<programlisting
>import dbus
kid3 = dbus.SessionBus().get_object(
  'org.kde.kid3', '/Kid3')
kid3.setFrame(2, 'Artist', 'Famoso Desconhecido')
</programlisting>
</listitem>
</varlistentry>
<varlistentry
><term
>Perl</term>
<listitem>
<programlisting
>use Net::DBus;
$kid3 = Net::DBus->session->get_service(
  "org.kde.kid3")->get_object(
  "/Kid3", "org.kde.Kid3");
$kid3->setFrame(2, "Artist", "Famoso Desconhecido");
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="dbus-api">
<title
>API de &DBus;</title>

<para
>A API de &DBus; está definida em <filename
>org.kde.Kid3.xml</filename
>. A interface do &kid3; tem os seguintes métodos: </para>

<sect2 id="dbus-openDirectory">
<title
>Abrir um ficheiro ou pasta</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>openDirectory</function
></funcdef
> <paramdef
>string <parameter
>localização</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>localização</replaceable
></term>
    <listitem
><para
>localização de um ficheiro ou pasta</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-unloadAllTags">
<title
>Descarrega as marcas de todos os ficheiros que não estejam modificados ou seleccionados</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>unloadAllTags</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-save">
<title
>Grava todos os ficheiros modificados</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>save</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-getErrorMessage">
<title
>Obtém uma mensagem de erro detalhada oferecida por alguns dos métodos</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>string <function
>getErrorMessage</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve uma mensagem de erro detalhada.</para>
</sect2>

<sect2 id="dbus-revert">
<title
>Reverte as modificações nos ficheiros seleccionados</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>revert</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-batchImport">
<title
>Inicia uma importação automática em lote</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>batchImport</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>nomePerfil</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>máscara de marcas (bit 0 para a marca 1, bit 1 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>nomePerfil</replaceable
></term>
    <listitem
><para
>nome do perfil de importação em lote a usar</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-importFromFile">
<title
>Importar as marcas de um ficheiro</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>importFromFile</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>localização</parameter
></paramdef
> <paramdef
>int32 <parameter
>indFmt</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>localização</replaceable
></term>
    <listitem
><para
>localização do ficheiro</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>indFmt</replaceable
></term>
    <listitem
><para
>índice do formato</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-importFromTags">
<title
>Importar as marcas de outras marcas</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>importFromTags</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>origem</parameter
></paramdef
> <paramdef
>string <parameter
>extracção</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>origem</replaceable
></term>
    <listitem
><para
>o formato para obter o texto da origem a partir das marcas</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>extracção</replaceable
></term>
    <listitem
><para
>expressão regular com os nomes dos pacotes e as capturas para extrair os dados a partir do texto de origem</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-importFromTagsToSelection">
<title
>Imptrar as marcas de outras marcas nos ficheiros seleccionados</title>
<funcsynopsis>
<funcprototype
><funcdef
>array <function
>importFromTagsToSelection</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>origem</parameter
></paramdef
> <paramdef
>string <parameter
>extracção</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>origem</replaceable
></term>
    <listitem
><para
>o formato para obter o texto da origem a partir das marcas</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>extracção</replaceable
></term>
    <listitem
><para
>expressão regular com os nomes dos pacotes e as capturas para extrair os dados a partir do texto de origem</para
></listitem>
  </varlistentry>
</variablelist>
<variablelist>
  <varlistentry>
    <term
><replaceable
>returnValues</replaceable
></term>
    <listitem
><para
>valor extraído para o "%{__return}(.+)"</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-downloadAlbumArt">
<title
>Obter as imagens da capa do álbum</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>downloadAlbumArt</function
></funcdef
> <paramdef
>string <parameter
>url</parameter
></paramdef
> <paramdef
>boolean <parameter
>todosFicheirosNaPasta</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>url</replaceable
></term>
    <listitem
><para
>&URL; do ficheiro da imagem ou recurso artístico do álbum</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>todosFicheirosNaPasta</replaceable
></term>
    <listitem
><para
>verdadeiro para adicionar a imagem a todos os ficheiros na pasta</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-exportToFile">
<title
>Exportar as marcas para um ficheiro</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>exportToFile</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>localização</parameter
></paramdef
> <paramdef
>int32 <parameter
>indFmt</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>localização</replaceable
></term>
    <listitem
><para
>localização do ficheiro</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>indFmt</replaceable
></term>
    <listitem
><para
>índice do formato</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-createPlaylist">
<title
>Criar uma lista de reprodução</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>createPlaylist</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-getPlaylistItems">
<title
>Obter os itens de uma lista de reprodução</title>
<funcsynopsis>
<funcprototype
><funcdef
>array <function
>getPlaylistItems</function
></funcdef
> <paramdef
>string <parameter
>localização</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>localização</replaceable
></term>
    <listitem
><para
>localização do ficheiro da lista de reprodução</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve uma lista com as localizações absolutas dos itens da lista de reprodução.</para>
</sect2>

<sect2 id="dbus-setPlaylistItems">
<title
>Define os itens de uma lista de reprodução</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>setPlaylistItems</function
></funcdef
> <paramdef
>string <parameter
>localização</parameter
></paramdef
> <paramdef
>array <parameter
>itens</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>localização</replaceable
></term>
    <listitem
><para
>localização do ficheiro da lista de reprodução</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>itens</replaceable
></term>
    <listitem
><para
>lista de localizações absolutas dos itens da lista de reprodução</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve verdadeiro se OK, ou falso se nem todos os itens foram encontrados ou se a adição ou gravação ou gravação foi mal-sucedida.</para>
</sect2>

<sect2 id="dbus-quit">
<title
>Sair da aplicação</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>quit</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-selectAll">
<title
>Seleccionar todos os ficheiros</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>selectAll</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-deselectAll">
<title
>Deseleccionar todos os ficheiros</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>deselectAll</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-firstFile">
<title
>Configura o primeiro ficheiro como o ficheiro actual</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>firstFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um primeiro ficheiro.</para>
</sect2>

<sect2 id="dbus-previousFile">
<title
>Configura o ficheiro anterior como sendo o actual</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>previousFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um ficheiro anterior.</para>
</sect2>

<sect2 id="dbus-nextFile">
<title
>Configura o ficheiro seguinte como sendo o actual</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>nextFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um ficheiro seguinte.</para>
</sect2>

<sect2 id="dbus-selectFirstFile">
<title
>Selecciona o primeiro ficheiro</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>selectFirstFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um primeiro ficheiro.</para>
</sect2>

<sect2 id="dbus-selectPreviousFile">
<title
>Seleccionar o ficheiro anterior</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>selectPreviousFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um ficheiro anterior.</para>
</sect2>

<sect2 id="dbus-selectNextFile">
<title
>Seleccionar o ficheiro seguinte</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>selectNextFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um ficheiro seguinte.</para>
</sect2>

<sect2 id="dbus-selectCurrentFile">
<title
>Seleccionar o ficheiro actual</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>selectCurrentFile</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se existe um ficheiro actual.</para>
</sect2>

<sect2 id="dbus-expandDirectory">
<title
>Expande ou fecha o item do ficheiro actual se for uma pasta</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>boolean <function
>expandDirectory</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Um item de lista de ficheiros é uma pasta se o getFileName() devolver um um nome com '/' como último carácter.</para>
<para
>Devolve verdadeiro se o item do ficheiro actual for uma pasta.</para>
</sect2>

<sect2 id="dbus-applyFilenameFormat">
<title
>Aplicar o formato de nomes dos ficheiros</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>applyFilenameFormat</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-applyTagFormat">
<title
>Aplicar o formato das marcas</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>applyTagFormat</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-applyTextEncoding">
<title
>Aplicar a codificação do texto</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>applyTextEncoding</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-setDirNameFromTag">
<title
>Definir o nome da pasta a partir das marcas</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>setDirNameFromTag</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>formato</parameter
></paramdef
> <paramdef
>boolean <parameter
>criar</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>máscara de marcas (bit 0 para a marca 1, bit 1 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>formato</replaceable
></term>
    <listitem
><para
>formato dos nomes dos ficheiros</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>criar</replaceable
></term>
    <listitem
><para
>verdadeiro para criar, falso para mudar o nome</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve verdadeiro se OK, caso contrário a mensagem de erro estará disponível se usar o  getErrorMessage().</para>
</sect2>

<sect2 id="dbus-numberTracks">
<title
>Define os números das faixas subsequentes nos ficheiros seleccionados</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>numberTracks</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>int32 <parameter
>nrPrimeiraFaixa</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>máscara de marcas (bit 0 para a marca 1, bit 1 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>nrPrimeiraFaixa</replaceable
></term>
    <listitem
><para
>número a usar para o primeiro ficheiro</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-filter">
<title
>Filtrar os ficheiros</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>filter</function
></funcdef
> <paramdef
>string <parameter
>expressão</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>expressão</replaceable
></term>
    <listitem
><para
>expressão de filtragem</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-convertToId3v24">
<title
>Converter as marcas de ID3v2.3 para ID3v2.4</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>convertToId3v24</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

<sect2 id="dbus-convertToId3v23">
<title
>Converter as marcas de ID3v2.4 para ID3v2.3</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>convertToId3v23</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-getDirectoryName">
<title
>Obter a localização da pasta</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>string <function
>getDirectoryName</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve a localização absoluta da pasta.</para>
</sect2>

<sect2 id="dbus-getFileName">
<title
>Obtém o nome do ficheiro actual</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>string <function
>getFileName</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>Devolve a localização absoluta do nome do ficheiro; termina com "/" se for uma pasta.</para>
</sect2>

<sect2 id="dbus-setFileName">
<title
>Define o nome do ficheiro seleccionado</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>setFileName</function
></funcdef
> <paramdef
>string <parameter
>nome</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>nome</replaceable
></term>
    <listitem
><para
>nome do ficheiro</para
></listitem>
  </varlistentry>
</variablelist>
<para
>O ficheiro irá mudar de nome quando a pasta for gravada.</para>
</sect2>

<sect2 id="dbus-setFileNameFormat">
<title
>Define o formato a usar quando definir o nome do ficheiro a partir das marcas</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>setFileNameFormat</function
></funcdef
> <paramdef
>string <parameter
>formato</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>formato</replaceable
></term>
    <listitem
><para
>formato dos nomes dos ficheiros</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-setFileNameFromTag">
<title
>Configura os nomes dos ficheiros para os ficheiros seleccionados a partir das marcas</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>setFileNameFromTag</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-getFrame">
<title
>Obter o valor do pacote</title>
<funcsynopsis>
<funcprototype
><funcdef
>string <function
>getFrame</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>nome</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>nome</replaceable
></term>
    <listitem
><para
>nome do pacote (<abbrev
>p.ex.</abbrev
> "artist")</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Para obter dados binários, como uma imagem, o nome do ficheiro a gravar pode ser adicionado a seguir ao <parameter
>name</parameter
>, <abbrev
>p.ex.</abbrev
> "Picture:/local/do/ficheiro". Da mesma forma, também poderão ser exportadas, <abbrev
>p.ex.</abbrev
> "SYLT:/local/do/ficheiro". </para>
<para
>Devolve o valor do pacote.</para>
</sect2>

<sect2 id="dbus-setFrame">
<title
>Configurar o valor do pacote</title>
<funcsynopsis>
<funcprototype
><funcdef
>boolean <function
>setFrame</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> <paramdef
>string <parameter
>nome</parameter
></paramdef
> <paramdef
>string <parameter
>valor</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>nome</replaceable
></term>
    <listitem
><para
>nome do pacote (<abbrev
>p.ex.</abbrev
> "artist")</para
></listitem>
  </varlistentry>
  <varlistentry>
    <term
><replaceable
>valor</replaceable
></term>
    <listitem
><para
>valor do pacote</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Para a marca 2 (<parameter
>tagMask</parameter
> 2), se não existir nenhum pacote chamado <parameter
>nome</parameter
>, será adicionado um novo pacote; se o <parameter
>valor</parameter
> estiver vazio, o pacote é removido. Para adicionar dados binários, como uma imagem, poderá adicionar um ficheiro a seguir ao <parameter
>nome</parameter
>, <abbrev
>p.ex.</abbrev
> "Picture:/local/do/ficheiro". "SYLT:/local/do/ficheiro" pode ser usado para importar as letras sincronizadas.</para>
<para
>Devolve verdadeiro se OK.</para>
</sect2>

<sect2 id="dbus-getTag">
<title
>Obter todos os pacotes de uma marca</title>
<funcsynopsis>
<funcprototype
><funcdef
>lista de textos <function
>getTag</function
></funcdef
> <paramdef
>int32 <parameter
>tagMask</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
<para
>Devolve uma lista com os nomes e valores dos pacotes de forma alternada.</para>
</sect2>

<sect2 id="dbus-getInformation">
<title
>Obter informações técnicas sobre o ficheiro</title>
<funcsynopsis>
<funcprototype>
  <funcdef
>lista de textos <function
>getInformation</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>As propriedades são o Formato, Taxa de Dados, Taxa de Amostragem, Canais, Duração, Modo do Canal, VBR, Marca 1, Marca 2. Propriedades; os que não estiverem disponíveis são omitidos.</para>
<para
>Devolve uma lista alternada entre os nomes e os valores das propriedades.</para>
</sect2>

<sect2 id="dbus-setTagFromFileName">
<title
>Configurar uma marca a partir do nome do ficheiro</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>setTagFromFileName</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-setTagFromOtherTag">
<title
>Configurar uma marca a partir de outra marca</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>setTagFromOtherTag</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-copyTag">
<title
>Copiar a marca</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>copyTag</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-pasteTag">
<title
>Colar a marca</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>pasteTag</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-removeTag">
<title
>Remover a marca</title>
<funcsynopsis>
<funcprototype
><funcdef
><function
>removeTag</function
></funcdef
> <paramdef
>int32 <parameter
>mascaraMarcas</parameter
></paramdef
> </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term
><replaceable
>mascaraMarcas</replaceable
></term>
    <listitem
><para
>bit da marca (1 para a marca 1, 2 para a marca 2)</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="dbus-reparseConfiguration">
<title
>Volta a processar a configuração</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>reparseConfiguration</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
<para
>As mudanças automatizadas da configuração serão possíveis se modificar o ficheiro de configuração e depois voltar a processar a configuração.</para>
</sect2>

<sect2 id="dbus-playAudio">
<title
>Reproduz os ficheiros seleccionados</title>
<funcsynopsis>
<funcprototype>
  <funcdef
><function
>playAudio</function
></funcdef>
  <void/>
</funcprototype>
</funcsynopsis>
</sect2>

</sect1>

</appendix>

<appendix id="qml-interface">
<title
>Interface em QML</title>

<sect1 id="qml-examples">
<title
>Exemplos em QML</title>

<para
>Os programas em QML podem ser invocados através do menu de contexto da lista de ficheiros e podem ser configurados na página <link linkend="configure-user-actions-qml"
>Acções do Utilizador</link
> da janela de configuração. Os programas que são aqui configurados podem ser usados como exemplos para programas personalizados. O QML usa o &javascript;, sendo que aqui está o obrigatório "Olá Mundo": </para>

<programlisting
>import Kid3 1.0

Kid3Script {
  onRun: {
    console.log("Olá mundo, a pasta é", app.dirName)
    Qt.quit()
  }
}
</programlisting>

<para
>Se este programa for gravado em <filename
>/local/do/Exemplo.qml</filename
>, o comando do utilizador poderá ser definido como <command
>@qml /local/do/Exemplo.qml</command
> com o nome <userinput
>Teste de QML</userinput
> e o <guilabel
>Resultado</guilabel
> assinalado. Poderá então ser iniciado com o item <guilabel
>Teste de QML</guilabel
> no menu de contexto da lista de ficheiros, ficando o resultado visível na janela. </para>

<para
>Em alternativa, o programa também pode ser iniciado de forma independente do &kid3;, usando as ferramentas de QML. <screen width="80">
qml -apptype widget -I /usr/lib/kid3/plugins/imports /local/do/Exemplo.qml
</screen
> or <screen width="80">
qmlscene -I /usr/lib/kid3/plugins/imports /local/do/Exemplo.qml
</screen
> No &Windows; e no &macOS;, a localização da importação deverá ser adaptada à pasta <filename
>imports</filename
> dentro da pasta de instalação. Os programas iniciados fora do &kid3; irão usar a pasta actual, pelo que a mesma deverá ser alterada de antemão. </para>

<para
>Para enumerar os títulos nas marcas 2 de todos os ficheiros na pasta actual, poderia ser usado o seguinte programa: </para>

<programlisting
>import Kid3 1.0

Kid3Script {
  onRun: {
    app.firstFile()
    do {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        console.log(app.getFrame(tagv2, "title"))
      }
    } while (app.nextFile())
  }
}
</programlisting>

<para
>Se a pasta tiver vários ficheiros, um destes programas poderá bloquear a interface do utilizador durante algum tempo. Para as operações mais demoradas, deverá então pausar de tempos a tempos. A implementação alternativa em baixo tem o trabalho feito para um único ficheiro transferido para uma função. Essa função invoca-se a si própria com um tempo-limite de 1 ms no fim, desde que existam mais ficheiros para serem processados. Isto irá garantir que a &GUI; continua a reagir enquanto o programa está em execução. </para>

<programlisting
>import Kid3 1.0

Kid3Script {
  onRun: {
    function trabalhar() {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        console.log(app.getFrame(tagv2, "title"))
      }
      if (!app.nextFile()) {
        Qt.quit()
      } else {
        setTimeout(trabalhar, 1)
      }
    }

    app.firstFile()
    trabalhar()
  }
}
</programlisting>

<para
>Ao usar o <command
>app.firstFile()</command
> com o <command
>app.nextFile()</command
>, serão processados todos os ficheiros na pasta actual. Se só é suposto processar os ficheiros seleccionados, use o <command
>firstFile()</command
> e o <command
>nextFile()</command
> em alternativa; estas são funções de conveniência do componente <classname
>Kid3Script</classname
>. O seguinte exemplo é um programa que copia apenas os pacotes do número do disco e dos direitos de cópia do ficheiro seleccionado. </para>

<programlisting
>import Kid3 1.1

Kid3Script {
  onRun: {
    function trabalhar() {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        app.setFrame(tagv2, "*.selected", false)
        app.setFrame(tagv2, "discnumber.selected", true)
        app.setFrame(tagv2, "copyright.selected", true)
        app.copyTags(tagv2)
      }
      if (!nextFile()) {
        Qt.quit()
      } else {
        setTimeout(trabalhar, 1)
      }
    }

    firstFile()
    trabalhar()
  }
}
</programlisting>

<para
>Mais programas vêm disponíveis com o &kid3; e estão já registados como comandos do utilizador. <itemizedlist>
<listitem
><para
><guilabel
>ReplayGain to SoundCheck</guilabel
> (<filename
>ReplayGain2SoundCheck.qml</filename
>): Criar a informação de SoundCheck do iTunNORM a partir dos pacotes de ganho de reprodução. </para
></listitem>
<listitem
><para
><guilabel
>Dimensionar as Imagens do Álbum</guilabel
> (<filename
>ResizeAlbumArt.qml</filename
>): Dimensiona as imagens das capas dos álbuns incorporadas que forem maiores que 500x500 pixels. </para
></listitem>
<listitem
><para
><guilabel
>Extrair as Imagens do Álbum</guilabel
> (<filename
>ExtractAlbumArt.qml</filename
>): Extrai todas as imagens incorporadas das capas, evitando os duplicados. </para
></listitem>
<listitem
><para
><guilabel
>Incorporar as Imagens do Álbum</guilabel
> (<filename
>EmbedAlbumArt.qml</filename
>): Incorpora as imagens de capas encontradas nos ficheiros de imagens dentro dos ficheiros de áudio na mesma pasta. </para
></listitem>
<listitem
><para
><guilabel
>Incorporar as Letras Musicais</guilabel
> (<filename
>EmbedLyrics.qml</filename
>): Obtém as letras musicais não sincronizadas a partir de um serviço na Web. </para
></listitem>
<listitem
><para
><guilabel
>Codificação de Texto do ID3v1</guilabel
> (<filename
>ShowTextEncodingV1.qml</filename
>): Ajuda a descobrir a codificação das marcas ID3v1, apresentando as marcas do ficheiro actual em todas as codificações de caracteres disponíveis. </para
></listitem>
<listitem
><para
><guilabel
>ID3v1 para ASCII</guilabel
> (<filename
>Tag1ToAscii.qml</filename
>): Traduz os caracteres acentuados estendidos na marca ID3v1 para ASCII. </para
></listitem>
<listitem
><para
><guilabel
>Capitalização de Títulos em Inglês</guilabel
> (<filename
>TitleCase.qml</filename
>): Formato o texto nas marcas como títulos em Inglês. </para
></listitem>
<listitem
><para
><guilabel
>Reescrever as Marcas</guilabel
> (<filename
>RewriteTags.qml</filename
>): Volta a gravar todas as marcas nos ficheiros seleccionados. </para
></listitem>
<listitem
><para
><guilabel
>Exportar para CSV</guilabel
> (<filename
>ExportCsv.qml</filename
>): Exporta de forma recursiva todas as marcas de todos os ficheiros para um ficheiro CSV. </para
></listitem>
<listitem
><para
><guilabel
>Exportar a Pasta da Lista de Reprodução</guilabel
> (<filename
>ExportPlaylist.qml</filename
>): Copiar todos os ficheiros de uma lista de reprodução para uma pasta e muda o nome delas de acordo com a sua posição. </para
></listitem>
<listitem
><para
><guilabel
>Consola de QML</guilabel
> (<filename
>QmlConsole.qml</filename
>): Uma consola simples para lidar com a API em QML do &kid3;. </para
></listitem>
</itemizedlist>
</para>

</sect1>

<sect1 id="qml-api">
<title
>API em QML</title>

<para
>A API pode ser explorada de forma simples com a Consola de QML, que está disponível como um programa de exemplo com uma interface de utilizador. </para>

<sect2 id="qml-kid3script">
<title
>Kid3Script</title>

<para
>O <classname
>Kid3Script</classname
> é um componente normal de QML que se localiza dentro da pasta de 'plugins'. Poderá usar outro componente de QML também. Ao usar o <classname
>Kid3Script</classname
>, fica mais fácil iniciar a função do programa com a rotina <function
>onRun</function
>. Para além disso, oferece algumas funções: <programlisting
>onRun: Tratamento de evento que é invocado quando o programa é iniciado
tagv1, tagv2, tagv2v1: Constantes para os parâmetros de marcas
script: Acesso às funções de programação
configs: Acesso às funções de configuração
getArguments(): Lista de argumentos do programa
isStandalone(): verdadeiro se o programa não foi iniciado dentro do Kid3
setTimeout(rotina, atraso): Inicia a rotina ao fim de 'atraso' ms
firstFile(): Para o primeiro ficheiro seleccionado
nextFile(): Para o ficheiro seguinte seleccionado
</programlisting>

</para>
</sect2>

<sect2 id="qml-script">
<title
>Funções de Programação</title>

<para
>Como o &javascript; e, por inerência, também o QML só têm um conjunto limitado de funções de programação, o objecto <function
>script</function
> tem alguns métodos adicionais, por exemplo: </para>

<programlisting
>script.properties(obj): Texto com as propriedades do Qt
script.writeFile(localFicheiro, dados): Grava os dados no ficheiro, verdadeiro se OK
script.readFile(localFicheiro): Lê dados do ficheiro
script.removeFile(localFicheiro): Apaga o ficheiro, verdadeiro se OK
script.fileExists(localFicheiro): verdadeiro se o ficheiro existe
script.fileIsWritable(localFicheiro): verdadeiro se o ficheiro pode ser gravado
script.getFilePermissions(localFicheiro): Obtém os bits do modo de permissão do ficheiro
script.setFilePermissions(localFicheiro, bitsModo): Altera os bits do modo de permissão do ficheiro
script.classifyFile(localFicheiro): Obtém a classe do ficheiro (pasta "/", ligação simb. "@", exe "*",
  ficheiro " ")
script.renameFile(nomeAntigo, nomeNovo): Muda o nome do ficheiro, verdadeiro se OK
script.copyFile(origem, destino): Copia o ficheiro, verdadeiro se OK
script.makeDir(local): Cria a pasta, verdadeiro se OK
script.removeDir(local): Remove a pasta, verdadeiro se OK
script.tempLocal(): Localização da pasta temporária
script.musicPath(): Localização da pasta de músicas
script.listDir(local, [filtrosNomes], [classificar]): Enumera os itens da pasta
script.system(programa, [args], [ms]): Inicia de forma síncrona um comando do sistema,
  [código de saída, standard output, standard error] caso não expire o tempo-limite
script.systemAsync(programa, [args], [rotina]): Invoca de forma assíncrona um comando do
sistema, sendo a 'rotina' invocada com o [código de saída, standard output, standard error]
script.getEnv(nomeVar): Devolve o valor da variável de ambiente
script.setEnv(nomeVar, valor): Altera o valor da variável de ambiente
script.getQtVersion(): Texto da versão do Qt, <abbrev
>p.ex.</abbrev
> "5.4.1"
script.getDataMd5(dados): Devolve o texto hexadecimal do código MD5 dos dados
script.getDataSize(dados): Devolve o tamanho da lista de 'bytes'
script.dataToImage(dados, [formato]): Cria uma imagem a partir dos 'bytes' de dados
script.dataFromImage(imagem, [formato]): Obtém os 'bytes' de dados a partir da imagem
script.loadImage(localFicheiro): Carrega uma imagem de um ficheiro
script.saveImage(img, localFicheiro, [formato]): Grava uma imagem para um ficheiro; verdadeiro se OK
script.imageProperties(img): Obtém as propriedades de uma imagem, sendo um mapa que contém os valores "width", "height", "depth" e "colorCount", vazio se a imagem for inválida
script.scaleImage(img, largura, [altura]): Ajusta a escala de uma imagem, devolvendo a imagem ajustada
</programlisting>

</sect2>

<sect2 id="qml-app">
<title
>Contexto da Aplicação</title>

<para
>Ao usar o QML, uma grande parte das funções do &kid3; estão disponíveis. A API é semelhante à usada no <link linkend="dbus-api"
>&DBus;</link
>. Para mais detalhes, consulte as notas respectivas. </para>

<programlisting
>app.openDirectory(local): Abrir a pasta
app.unloadAllTags(): Fechar todas as marcas
app.saveDirectory(): Grava a pasta
app.revertFileModifications(): Reverter
app.importTags(marca, local, incFmt): Importa o ficheiro
app.importFromTags(marca, origem, extracção): Importa a partir das marcas
app.importFromTagsToSelection(marca, origem, extracção): Importa a partir das marcas dos ficheiros seleccionados
app.downloadImage(url, todosFicheirosNaPasta): Obtém a imagem
app.exportTags(marca, local, indFmt): Exporta o ficheiro
app.writePlaylist(): Grava a lista de reprodução
app.getPlaylistItems(local): Obtém os itens de uma lista de reprodução
app.setPlaylistItems(local, itens): Define os itens de uma lista de reprodução
app.selectAllFiles(): Selecciona tudo
app.deselectAllFiles(): Deselecciona tudo
app.firstFile([seleccionar], [soFicheirosMarcados]): Para o primeiro ficheiro
app.nextFile([seleccionar], [soFicheirosMarcados]): Para o ficheiro seguinte
app.previousFile([seleccionar], [soFicheirosMarcados]): Para o ficheiro anterior
app.selectCurrentFile([seleccionar]): Selecciona o ficheiro actual
app.selectFile(local, [seleccionar]): Selecciona um ficheiro específico
app.getSelectedFilePaths([soFicheirosMarcados]): Obtém as localizações dos ficheiros seleccionados
app.requestExpandFileList(): Expandir tudo
app.applyFilenameFormat(): Aplica o formato dos nomes de ficheiros
app.applyTagFormat(): Aplica o formato das marcas
app.applyTextEncoding(): Aplica a codificação de texto
app.numberTracks(num, total, marca, [opções]): Numera as faixas
app.applyFilter(expr): Filtra
app.convertToId3v23(): Converte de ID3v2.4.0 para ID3v2.3.0
app.convertToId3v24(): Converte de ID3v2.3.0 para ID3v2.4.0
app.getFilenameFromTags(marca): Nome do ficheiro a partir das marcas
app.getTagsFromFilename(marca): Nome do ficheiro para marcas
app.getAllFrames(marca): Obtém o objecto com todos os pacotes
app.getFrame(marca, nome): Obtém o pacote
app.setFrame(marca, nome, valor): Configura o pacote
app.getPictureData(): Obtém os dados do pacote de imagem
app.setPictureData(dados): Modifica os dados do pacote de imagem
app.copyToOtherTag(marca): Copia uma marca para outra
app.copyTags(marca): Copiar
app.pasteTags(marca): Colar
app.removeTags(marca): Remover
app.playAudio(): Reproduzir
app.readConfig(): Lê a configuração
app.applyChangedConfiguration(): Aplica a configuração
app.dirName: Nome da pasta
app.selectionInfo.fileName: Nome do ficheiro
app.selectionInfo.filePath: Localização absoluta do ficheiro
app.selectionInfo.detailInfo: Detalhes do formato
app.selectionInfo.tag(Frame.Tag_1).tagFormat: Formato da marca 1
app.selectionInfo.tag(Frame.Tag_2).tagFormat: Formato da marca 2
app.selectionInfo.formatString(marca, formato): Substitui os códigos no texto do formato
app.selectFileName(titulo, pasta, filtro, gravarFicheiro): Abre uma janela para seleccionar um ficheiro
app.selectDirName(titulo, pasta): Abre a janela de ficheiros para seleccionar uma pasta
</programlisting>

<para
>Para as operações assíncronas, poderá associar rotinas aos eventos dos sinais. </para>

<programlisting
>function automaticImport(profile) {
  function onAutomaticImportFinished() {
    app.batchImporter.finished.disconnect(onAutomaticImportFinished)
  }
  app.batchImporter.finished.connect(onAutomaticImportFinished)
  app.batchImport(profile, tagv2)
}

function renameDirectory(format) {
  function onRenameActionsScheduled() {
    app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
    app.performRenameActions()
  }
  app.renameActionsScheduled.connect(onRenameActionsScheduled)
  app.renameDirectory(tagv2v1, format, false)
}
</programlisting>

</sect2>

<sect2 id="qml-configs">
<title
>Objectos de Configuração</title>

<para
>As diferentes secções de configuração estão acessíveis através de métodos do <function
>configs</function
>. As suas propriedades poderão ser listadas na consola de QML. <screen width="80">
script.properties(configs.networkConfig())
</screen
> As propriedades poderão ser alteradas: <screen width="80"
>configs.networkConfig().useProxy = false
</screen>
</para>

<programlisting
>configs.batchImportConfig()
configs.exportConfig()
configs.fileConfig()
configs.filenameFormatConfig()
configs.filterConfig()
configs.findReplaceConfig()
configs.guiConfig()
configs.importConfig()
configs.mainWindowConfig()
configs.networkConfig()
configs.numberTracksConfig()
configs.playlistConfig()
configs.renDirConfig()
configs.tagConfig()
configs.tagFormatConfig()
configs.userActionsConfig()
</programlisting>

</sect2>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: nxml
End:
-->
