Balanced Audio Controller – Speed, Volume & Loudness

AnkiWeb addon 1090755758

Adds speed and volume controls, loudness normalization modes, persistent deck audio analysis, and optional FFmpeg-based normalized copies while preserving original audio files.
AI-generated summary; may contain mistakes.

review-flownote-managementcard-templates

Open on AnkiWeb GitHub Find alternatives

AnkiWeb

Votes
0 (👍 0 · 👎 0)
Updated
2026-10-05
Anki versions
26.09.3~
License
MIT (from the license file in the package)
Virus scan
No ClamAV match A match does not prove malware. No match does not prove that the code is safe.
Languages
Python, JavaScript, CSS, JSON
Description language
pt

Maintenance

active

  • Last update or commit: 2026-10-05 (27 days before the snapshot).
  • Test files: 8.
  • GitHub Actions workflows: 11.
  • Commits in the last year: 176.
  • Issues: 0 open, 0 closed.
  • Pull requests: 0 open, 14 merged.

Will it work on my Anki?

Version branches
Min AnkiMax AnkiUpdated
26.08.126.09.3+2026-10-05
History across monthly snapshots

Loading…

Similar addons

Audio Normalizer

Measures card audio and creates verified, volume-adjusted copies for consistent loudness, with batch, preview, automatic, and original-restoring options.

note-managementbeta

1 votes 21% approval 👍 1 · 👎 0 ⭐ 0 Anki 26.05~ Updated 2026-08-12
Answer Time Alarm

Adds separate countdown timers and audio alarms for question and answer phases, with an optional visual bar, adjustable timing, persistent settings, and automatic disabling on cards containing audio.

review-flowtimer

1 votes 21% approval 👍 1 · 👎 0 Anki 25.02.5~ Updated 2026-04-08
PronounceIt

Provides instant audio and written pronunciations for 95,902 medical terms during Anki review, with downloadable offline audio, custom corrections, saved terms, and configurable settings.

review-flowshortcutsdictionary

1 votes 21% approval 👍 1 · 👎 0 ⭐ 1 Anki 2.1.1~ Updated 2026-09-22

Description

Balanced Audio Controller

Balanced Audio Controller is a free and open-source add-on for Anki Desktop that improves audio playback while preserving Anki's native audio system.

It provides:

  • Playback speed control
  • Volume control
  • Three normalization/playback modes
  • OverVolume with protected extra gain
  • Full deck audio analysis
  • Persistent per-deck normalization profiles
  • Built-in analysis without requiring an external FFmpeg executable
  • Optional FFmpeg installation
  • Creation of permanent pre-normalized audio copies
  • Automatic normalized-audio field creation
  • Automatic card-template integration for generated audio
  • Preservation of the original audio together with the normalized copy
  • A draggable and minimizable reviewer panel
  • Organized settings for Playback, Analysis, and Created Audio

The add-on never overwrites or removes your original audio files.

When normalized copies are created, they are added as extra media files. The original audio remains untouched and continues to exist in the card.

Supported Languages / Idiomas Suportados

Currently supported:

  • English
  • Português (Brasil)

Default language:

auto

In automatic mode, the add-on detects the operating-system language.

Portuguese systems use Português (Brasil).

Unsupported languages fall back to English.

The language can also be selected from the Balanced Audio Controller settings.

English

Audio Control Panel

Balanced Audio Controller adds a compact floating audio panel to cards that contain audio.

The panel does not replace Anki's original audio system.

Anki remains responsible for native playback and replay, while Balanced Audio Controller adjusts the native player when dynamic audio processing is required.

The panel is organized into three groups:

Playback

  • Playback speed
  • Volume

Normalization

  • Playback mode
  • OverVolume
  • Current mode status

Deck

  • Deck analysis status
  • Analyze Deck

The panel can be moved by dragging its title bar.

Double-click the title bar to restore the default position.

The panel can also be minimized, leaving only its title bar visible.

Its position and minimized state are remembered.

Advanced options are available under:

Tools → Balanced Audio Controller → Settings

The settings window is organized into:

  • Playback
  • Analysis
  • Created Audio

Playback Modes

Balanced Audio Controller provides three exclusive processing modes.

Only one mode is selected at a time.

The selected mode determines how Balanced Audio Controller processes the original audio during playback.

A physical bac_norm_* audio copy that is already present in the card is considered already normalized and is not normalized again.

1. Analyzed Profile

Analyzed Profile uses the gain calculated when the deck was analyzed.

Each original audio file can receive an individual gain adjustment based on its measured loudness.

This is especially useful for decks containing many short recordings, such as:

  • language-learning decks;
  • pronunciation exercises;
  • vocabulary recordings;
  • sentence audio;
  • speech samples.

The gain adjustment is applied only during playback.

The original audio file is never modified.

If the profile is missing or outdated for an audio file, this mode does not silently switch to another normalization method.

2. Real Time

Real Time applies the loudnorm filter while the original audio is playing.

This mode works immediately and does not require the deck to be analyzed first.

It uses audio filters available through Anki's native MPV playback system.

A standalone FFmpeg installation is therefore not required just to use real-time normalization.

For very short recordings, dynamic normalization has less time to analyze the complete signal.

For those decks, an analyzed profile or a permanently generated normalized copy may provide more consistent results.

3. Created Audio

Created Audio is designed for decks that contain permanent normalized copies generated by Balanced Audio Controller.

Generated files use names beginning with:

bac_norm_

These files are physically stored in Anki's media collection.

They are referenced through native Anki audio references such as:

[sound:bac_norm_....m4a]

The generated copy does not replace the original audio

After normalized audio is created, the card keeps:

  • the original audio and its native audio reference/player;
  • the normalized copy and its native audio reference/player.

Balanced Audio Controller does not:

  • delete the original;
  • overwrite the original;
  • rename the original;
  • remove the original from the card;
  • temporarily replace the original in memory.

The normalized copy is an additional physical media file.

Because bac_norm_* files are already normalized, Balanced Audio Controller does not apply normalization again to those files during playback.

This prevents double normalization.

The card template is the source of truth for the generated audio.

If the add-on is disabled or removed, the normalized copy can continue working through Anki's native audio system because both the physical media file and its [sound:...] reference remain stored in the collection/card.

Target Loudness

The Target Loudness setting defines the desired perceived loudness.

Unit:

LUFS

Available range:

-50 LUFS to -20 LUFS

Default:

-24 LUFS

Values closer to -20 LUFS produce louder output.

Values closer to -50 LUFS produce quieter output.

The same target is used by:

  • deck analysis;
  • analyzed profiles;
  • real-time normalization;
  • generated normalized copies.

Balanced Audio Controller also applies peak-safety limits to reduce the risk of clipping when amplification is required.

OverVolume

OverVolume is an optional playback-only boost for situations where the audio is still too quiet even when the regular volume control is at 100%.

Available boost:

0 dB to +12 dB

Default configured boost:

+6 dB

OverVolume is applied after the selected normalization mode.

A limiter is applied afterward to reduce the risk of digital clipping.

Limiter ceiling:

approximately -1.5 dBFS

OverVolume:

  • does not modify the original audio file;
  • does not modify generated bac_norm_* files;
  • does not create new media;
  • affects playback only.

Higher gain values can make background noise or distortion already present in the source more noticeable.

Dual-Mono

The Treat mono as dual-mono option changes loudness measurement for mono recordings intended to be reproduced equally through stereo channels.

This can be useful for:

  • language-learning decks;
  • pronunciation recordings;
  • voice recordings;
  • mono speech files.

Changing this setting can make an existing analyzed profile outdated.

Analyze Deck

Analyze Deck scans the current deck and analyzes the original audio files used by its cards.

Generated bac_norm_* files are excluded from analysis so they are not analyzed again as source audio.

For each supported source file, Balanced Audio Controller calculates the information required to determine an appropriate gain adjustment.

The resulting profile is stored persistently.

You do not need to analyze the deck every time Anki starts.

The profile remains available after:

  • closing Anki;
  • restarting Anki;
  • restarting the computer.

Profiles are stored separately from the original media.

Deck analysis does not automatically change the selected playback mode.

Analysis and normalized-audio generation are also coordinated so that conflicting operations are not started at the same time.

Deck Analysis Methods

Balanced Audio Controller provides three analysis methods.

Automatic

Recommended for most users.

Automatic:

  1. Uses FFmpeg when it is available.
  2. Falls back to the built-in analyzer when FFmpeg is unavailable.

This means Analyze Deck can work without installing an external FFmpeg executable.

FFmpeg

Uses FFmpeg's loudnorm analysis for more accurate full-file loudness measurements.

FFmpeg can be:

  • detected from the operating system; or
  • installed through Balanced Audio Controller on supported platforms.

FFmpeg is also required when creating physical normalized audio copies because those files need to be encoded and written to Anki's media collection.

Built-in Analyzer — No External FFmpeg

The built-in analyzer works without an external FFmpeg executable.

It uses audio decoding capabilities available through Anki's Qt WebEngine/WebAudio environment.

This method provides a way to balance deck volume without installing FFmpeg.

Its loudness measurement is approximate and is not a replacement for FFmpeg's complete EBU R128 implementation.

For the most accurate analysis, use FFmpeg.

Optional FFmpeg Installation

If FFmpeg is unavailable and the current platform is supported, Balanced Audio Controller can offer:

Install FFmpeg

Installation starts only after explicit user action.

The add-on does not silently install external software.

The managed FFmpeg executable is stored inside the add-on's persistent files and does not replace the operating system's FFmpeg installation.

Administrator/root access is not normally required.

If FFmpeg installation is declined or fails:

  • normal Anki playback continues working;
  • speed and volume continue working;
  • real-time normalization continues working;
  • the built-in analyzer remains available.

Creating physical normalized audio copies still requires FFmpeg.

Creating Normalized Audio Copies

After analyzing a deck, Balanced Audio Controller can create permanent normalized copies of its audio files.

Use:

Create normalized copies

This process requires FFmpeg.

For each analyzed source file, the add-on creates an additional normalized media file.

Example:

Original:

audio.mp3

Generated copy:

bac_norm_..._audio.m4a

The exact filename is generated automatically.

The original file remains intact

Balanced Audio Controller does not:

  • delete it;
  • overwrite it;
  • rename it;
  • replace its reference in the card.

The generated copy is imported through Anki's media system and stored as additional collection media.

After creation, the note can permanently contain both:

  • the original audio;
  • the normalized copy.

BAC Normalized Audio Field

Balanced Audio Controller creates a dedicated note field:

BAC Áudio Normalizado

This field stores native Anki audio references such as:

[sound:bac_norm_....m4a]

If a field with that name already exists and contains unrelated user data, Balanced Audio Controller can use a numbered alternative instead of overwriting existing information.

The normalized-audio field is separate from the original audio field.

This allows the note to permanently keep both audio versions.

Add Normalized Audio to the Card HTML

When normalized audio is generated, Balanced Audio Controller integrates the dedicated normalized-audio field into the card template.

The add-on detects the appropriate card side and inserts the normalized field into the corresponding HTML.

Conceptually, the card keeps two native audio references.

Original:

[sound:audio.mp3]

Normalized copy:

[sound:bac_norm_..._audio.m4a]

The original reference remains intact.

The normalized reference is added as a second native audio player/reference.

The generated audio does not depend on an in-memory replacement performed by the add-on.

A maintenance action can also prepare or repair the normalized-audio field and template integration using generated media that already exists.

This can be useful for decks processed by older versions of Balanced Audio Controller.

Recommended Workflow

For a deck with inconsistent audio volume:

  1. Open a card from the deck.
  2. Open Tools → Balanced Audio Controller → Settings.
  3. Set the desired Target Loudness.
  4. Leave the analysis method on Automatic, or select FFmpeg/Built-in manually.
  5. Click Analyze Deck.
  6. Choose the desired playback behavior.

For non-destructive playback without creating additional media:

Analyzed Profile

For immediate normalization without deck analysis:

Real Time

For permanent normalized media:

  1. Analyze the deck.
  2. Click Create normalized copies.
  3. Balanced Audio Controller creates physical bac_norm_* files.
  4. The dedicated normalized-audio field receives native [sound:...] references.
  5. The normalized-audio field is integrated into the card template.
  6. The original audio remains unchanged.
  7. The card now contains both the original audio and the normalized copy.
  8. Select Created Audio when using the already-generated media without additional normalization being applied to bac_norm_* files.

When Should I Analyze the Deck Again?

Reanalyze the deck when:

  • new original audio files are added;
  • existing source audio files are replaced;
  • the deck changes significantly;
  • Target Loudness changes;
  • the dual-mono option changes.

If important normalization settings change, an existing profile may be considered outdated.

If you use generated normalized audio, create the copies again after changing normalization parameters if you want the physical copies to reflect the new values.

Original Audio Safety

Balanced Audio Controller is designed to preserve original deck media.

It does not overwrite or remove your original audio when:

  • analyzing a deck;
  • using Analyzed Profile;
  • using Real Time normalization;
  • creating normalized copies;
  • using OverVolume.

Generated normalized audio is stored as additional media.

The original field/reference remains intact.

The normalized copy is stored separately and added to the card template as an additional native audio reference.

If the add-on is disabled or removed:

  • original media remains available;
  • generated bac_norm_* media remains in the collection;
  • native [sound:...] references remain in the note/template;
  • generated audio does not depend on Balanced Audio Controller to be located or played by Anki.

Português (Brasil)

Painel de Controle de Áudio

O Balanced Audio Controller adiciona um painel flutuante compacto aos cartões que possuem áudio.

Ele não substitui o sistema nativo de áudio do Anki.

O Anki continua responsável pela reprodução e replay, enquanto o Balanced Audio Controller ajusta o player nativo quando algum processamento dinâmico é necessário.

O painel é organizado em três grupos:

Reprodução

  • Velocidade
  • Volume

Normalização

  • Modo de reprodução
  • OverVolume
  • Estado do modo atual

Deck

  • Estado da análise
  • Analisar deck

O painel pode ser arrastado pela tela.

Dê dois cliques na barra superior para restaurar sua posição padrão.

Também é possível minimizar o painel e deixar apenas sua barra superior visível.

A posição e o estado minimizado são salvos.

As configurações avançadas ficam em:

Ferramentas → Balanced Audio Controller → Configurações

A janela de configurações é organizada em:

  • Reprodução
  • Análise
  • Áudios criados

Modos de Reprodução

O Balanced Audio Controller possui três modos exclusivos de processamento.

Somente um modo é selecionado por vez.

O modo selecionado define como o Balanced Audio Controller processa o áudio original durante a reprodução.

Uma cópia física bac_norm_* que já esteja presente no cartão é considerada normalizada e não recebe normalização novamente.

1. Perfil Analisado

Perfil analisado utiliza o ganho calculado durante a análise do deck.

Cada arquivo original pode possuir seu próprio ajuste de ganho conforme o loudness medido.

Esse modo é especialmente útil para decks com muitos áudios curtos, por exemplo:

  • estudo de idiomas;
  • pronúncia;
  • vocabulário;
  • frases;
  • gravações de voz.

O ajuste é aplicado somente durante a reprodução.

O arquivo original não é modificado.

Se um áudio não possuir uma entrada válida no perfil ou o perfil estiver desatualizado, o modo não troca silenciosamente para outra forma de normalização.

2. Em Tempo Real

Em tempo real aplica o filtro loudnorm enquanto o áudio original está sendo reproduzido.

Funciona imediatamente e não exige analisar o deck antes.

Esse modo utiliza os filtros disponíveis através do MPV nativo do Anki.

Por isso, não é necessário possuir um executável FFmpeg externo apenas para utilizar a normalização durante a reprodução.

Em gravações muito curtas, o filtro dinâmico possui menos tempo para avaliar o sinal completo.

Nesses casos, Perfil analisado ou uma cópia física previamente normalizada pode apresentar resultados mais consistentes.

3. Áudios Criados

Áudios criados foi desenvolvido para decks que possuem cópias normalizadas permanentes geradas pelo Balanced Audio Controller.

Os arquivos criados possuem nomes iniciados por:

bac_norm_

Esses arquivos ficam fisicamente armazenados na coleção de mídia do Anki.

Eles são referenciados através de referências nativas do Anki, por exemplo:

[sound:bac_norm_....m4a]

A cópia normalizada não substitui o áudio original

Depois da geração, o cartão mantém:

  • o áudio original e sua referência/player nativo;
  • a cópia normalizada e sua referência/player nativo.

O Balanced Audio Controller não:

  • apaga o áudio original;
  • sobrescreve o áudio original;
  • renomeia o áudio original;
  • remove o original do cartão;
  • substitui temporariamente o original apenas durante a reprodução.

A cópia normalizada é um arquivo físico adicional.

Como os arquivos bac_norm_* já estão normalizados, o add-on não aplica novamente outra normalização sobre eles.

Isso evita normalização dupla.

O template do cartão é a fonte de verdade para o áudio gerado.

Se o add-on for desativado ou removido, a cópia normalizada continua podendo funcionar através do próprio sistema nativo do Anki, porque tanto o arquivo físico quanto a referência [sound:...] continuam gravados.

Loudness Alvo

A configuração Loudness alvo define o volume percebido desejado.

Unidade:

LUFS

Intervalo:

-50 LUFS até -20 LUFS

Padrão:

-24 LUFS

Valores próximos de -20 LUFS produzem um áudio mais alto.

Valores próximos de -50 LUFS produzem um áudio mais baixo.

O mesmo alvo é utilizado por:

  • análise do deck;
  • Perfil analisado;
  • normalização Em tempo real;
  • criação das cópias normalizadas.

O Balanced Audio Controller também utiliza limites de pico para reduzir o risco de clipping quando um áudio precisa ser amplificado.

OverVolume

OverVolume é um ganho extra opcional aplicado somente durante a reprodução.

Ele é útil quando o áudio continua baixo mesmo com o controle de volume normal em 100%.

Intervalo:

0 dB até +12 dB

Valor configurado por padrão:

+6 dB

O OverVolume é aplicado depois do modo de normalização selecionado.

Em seguida, um limitador é utilizado para reduzir o risco de clipping digital.

Teto aproximado do limitador:

-1,5 dBFS

O OverVolume:

  • não altera o áudio original;
  • não altera arquivos bac_norm_*;
  • não cria novos arquivos de mídia;
  • atua somente durante a reprodução.

Valores altos podem deixar mais perceptíveis ruídos ou distorções que já existam na gravação.

Dual-Mono

A opção Tratar mono como dual-mono altera o cálculo de loudness para gravações mono que serão reproduzidas igualmente em canais estéreo.

Pode ser útil para:

  • decks de idiomas;
  • gravações de pronúncia;
  • gravações de voz;
  • arquivos mono.

Alterar essa opção pode deixar um perfil analisado existente desatualizado.

Analisar Deck

Analisar deck procura os arquivos de áudio originais utilizados pelos cartões do deck atual.

Cópias bac_norm_* são ignoradas durante a análise para não serem tratadas como novos arquivos de origem.

Cada arquivo compatível é analisado e o Balanced Audio Controller calcula o ajuste de ganho necessário.

O resultado é armazenado em um perfil persistente.

Não é necessário analisar novamente sempre que abrir o Anki.

O perfil continua disponível depois de:

  • fechar o Anki;
  • abrir o Anki novamente;
  • reiniciar o computador.

Os dados do perfil ficam separados dos arquivos de mídia originais.

A análise não altera automaticamente o modo de reprodução selecionado.

As operações de análise e geração de cópias também são coordenadas para evitar conflitos entre os dois processos.

Métodos de Análise

Existem três métodos disponíveis.

Automático

Recomendado para a maioria dos usuários.

O modo Automático:

  1. Usa FFmpeg quando ele está disponível.
  2. Usa o analisador interno quando FFmpeg não está disponível.

Portanto, Analisar deck pode funcionar sem instalar um executável FFmpeg externo.

FFmpeg

Utiliza a análise loudnorm do FFmpeg para uma medição completa e mais precisa do arquivo.

O FFmpeg pode ser:

  • encontrado automaticamente no sistema; ou
  • instalado pelo Balanced Audio Controller em plataformas compatíveis.

O FFmpeg também é necessário para criar arquivos físicos normalizados, pois esses novos arquivos precisam ser codificados e gravados na coleção de mídia do Anki.

Analisador Interno — Sem FFmpeg Externo

O analisador interno não exige um executável FFmpeg externo.

Ele utiliza os recursos de decodificação disponíveis através do Qt WebEngine/WebAudio do Anki.

Esse método oferece uma forma de equilibrar o volume do deck quando o usuário não deseja instalar FFmpeg.

A medição é aproximada e não substitui a implementação completa EBU R128 do FFmpeg.

Para maior precisão, utilize FFmpeg.

Instalação Opcional do FFmpeg

Se FFmpeg não estiver disponível e a plataforma for compatível, o Balanced Audio Controller pode apresentar:

Instalar FFmpeg

A instalação só começa após uma ação explícita do usuário.

O add-on não instala programas silenciosamente.

O FFmpeg gerenciado fica armazenado nos arquivos persistentes do próprio add-on e não substitui uma instalação já existente no sistema.

Normalmente não é necessário acesso de administrador/root.

Se a instalação não for feita ou falhar:

  • a reprodução normal do Anki continua funcionando;
  • velocidade e volume continuam funcionando;
  • a normalização Em tempo real continua disponível;
  • o analisador interno continua disponível.

A criação de cópias físicas normalizadas continua exigindo FFmpeg.

Criar Cópias Normalizadas

Depois de analisar um deck, o Balanced Audio Controller pode gerar arquivos físicos e permanentes já normalizados.

Utilize:

Criar cópias normalizadas

Essa operação exige FFmpeg.

Para cada áudio analisado, o add-on cria um arquivo adicional.

Exemplo:

Original:

audio.mp3

Cópia normalizada:

bac_norm_..._audio.m4a

O nome completo é criado automaticamente.

O original permanece intacto

O Balanced Audio Controller não:

  • apaga o original;
  • sobrescreve o original;
  • renomeia o original;
  • remove sua referência do cartão.

A nova mídia é importada através do sistema de mídia do Anki e armazenada como um arquivo adicional na coleção.

Depois da criação, a nota pode manter simultaneamente:

  • o áudio original;
  • a cópia normalizada.

Campo BAC Áudio Normalizado

O Balanced Audio Controller cria um campo dedicado chamado:

BAC Áudio Normalizado

Esse campo armazena referências nativas de áudio do Anki:

[sound:bac_norm_....m4a]

Se já existir um campo com esse nome contendo informações não relacionadas ao add-on, uma alternativa numerada pode ser utilizada para evitar sobrescrever dados do usuário.

O campo normalizado é separado do campo que contém o áudio original.

Assim, a nota mantém permanentemente as duas versões.

Inserir Áudio Normalizado no HTML do Card

Ao criar os áudios normalizados, o Balanced Audio Controller integra o campo dedicado ao template do cartão.

O add-on identifica a face correspondente e adiciona o campo BAC Áudio Normalizado ao HTML.

Conceitualmente, o cartão mantém duas referências nativas.

Original:

[sound:audio.mp3]

Cópia normalizada:

[sound:bac_norm_..._audio.m4a]

A referência original é preservada.

A referência normalizada é adicionada como um segundo áudio/player nativo.

O funcionamento da cópia não depende de uma substituição temporária feita em memória pelo add-on.

Também existe uma ação de manutenção capaz de preparar ou reparar o campo e o template utilizando cópias físicas que já existam, sem precisar recodificar novamente os áudios.

Isso é útil para decks processados por versões anteriores.

Fluxo Recomendado

Para um deck com volumes muito diferentes:

  1. Abra um cartão do deck.
  2. Abra Ferramentas → Balanced Audio Controller → Configurações.
  3. Escolha o Loudness alvo.
  4. Mantenha o método Automático ou escolha FFmpeg/Interno manualmente.
  5. Clique em Analisar deck.
  6. Escolha o comportamento desejado.

Para normalização não destrutiva sem criar novos arquivos:

Perfil analisado

Para normalização imediata sem analisar o deck:

Em tempo real

Para criar mídia normalizada permanente:

  1. Analise o deck.
  2. Clique em Criar cópias normalizadas.
  3. O Balanced Audio Controller cria os arquivos bac_norm_*.
  4. O campo dedicado recebe referências nativas [sound:...].
  5. O campo normalizado é integrado ao template do cartão.
  6. O áudio original permanece intacto.
  7. O cartão passa a possuir o áudio original e a cópia normalizada.
  8. Selecione Áudios criados para trabalhar com as mídias já geradas sem aplicar nova normalização aos arquivos bac_norm_*.

Quando Devo Analisar Novamente?

É recomendado analisar novamente quando:

  • novos áudios originais forem adicionados;
  • arquivos de origem forem substituídos;
  • o deck sofrer alterações significativas;
  • o Loudness alvo for alterado;
  • a configuração dual-mono for alterada.

Se configurações importantes da análise forem modificadas, o perfil existente pode ser marcado como desatualizado.

Caso utilize cópias físicas normalizadas, gere novas cópias depois de alterar os parâmetros de normalização se quiser que os arquivos criados reflitam os novos valores.

Segurança dos Áudios Originais

O Balanced Audio Controller foi desenvolvido para preservar a mídia original.

Ele não sobrescreve nem remove seus arquivos de áudio originais ao:

  • analisar o deck;
  • usar Perfil analisado;
  • usar normalização Em tempo real;
  • criar cópias normalizadas;
  • usar OverVolume.

Os áudios normalizados são adicionados como novos arquivos.

O campo e a referência do áudio original permanecem intactos.

A cópia normalizada fica armazenada separadamente e é adicionada ao template do cartão como uma referência nativa adicional.

Se o add-on for desativado ou removido:

  • a mídia original continua disponível;
  • os arquivos bac_norm_* continuam na coleção;
  • as referências [sound:...] continuam na nota/template;
  • os cartões não dependem do Balanced Audio Controller para localizar as mídias que já foram criadas.

Source Code / Código-fonte

Balanced Audio Controller is free and open source.

Balanced Audio Controller é gratuito e de código aberto.

Source code / Código-fonte:

https://github.com/ferreis/Balanced_Audio_Controller

License / Licença:

MIT License

README

Balanced Audio Controller v1.1.0

Free and open-source audio controller for Anki Desktop. It keeps Anki's native MPV playback while adding speed, volume, loudness normalization, persistent per-deck audio profiles, optional FFmpeg installation, a built-in analyzer that works without FFmpeg, and a minimizable floating panel.

Extensão gratuita e de código aberto para Anki Desktop. Mantém a reprodução nativa pelo MPV e adiciona velocidade, volume, normalização de loudness, perfis persistentes por deck, instalação opcional do FFmpeg, analisador interno que funciona sem FFmpeg e painel flutuante minimizável.


English

Languages

Supported languages:

  • English (en)
  • Brazilian Portuguese (pt-BR)

Default configuration:

"language": "auto"

auto detects the operating-system locale. Portuguese locales use pt-BR; unsupported locales fall back to English.

Change it in Tools → Add-ons → Balanced Audio Controller → Config/Configure by setting language to auto, en, or pt-BR.

Playback controls

  • Speed: 0.25x to 2.0x, default 1.0x.
  • − and + change speed by 0.5x.
  • Manual numeric speed input is supported.
  • Volume: 0% to 100%.
  • The original Anki play/replay buttons remain native and are not replaced.
  • The floating panel is draggable; double-click its title bar to reset its position.
  • The − button in the panel title minimizes the add-on to its title bar. When minimized, the button changes to + so the panel can be expanded again.
  • The minimized/expanded state is stored locally and restored on later cards.

Real-time normalization

When enabled, the add-on applies loudnorm through Anki's MPV player during playback.

  • Target loudness: -50 to -20 LUFS.
  • Default: -24 LUFS.
  • True peak ceiling: -1.5 dBTP.
  • LRA target: 7 LU.
  • Optional dual-mono compensation for mono recordings played through stereo output.

This mode does not require a standalone ffmpeg executable because it uses the filters available through Anki/MPV.

Deck profile analysis

The deck profile analyzes each audio file and stores only the calculated gain. Original deck media is never rewritten or re-encoded.

The profile is stored in:

user_files/deck_profiles.json

It remains available after Anki or the computer is restarted.

Analysis methods

The add-on supports three modes through analysis_backend:

auto
ffmpeg
webaudio

auto (recommended)

  • Uses standalone FFmpeg when it is available.
  • Automatically falls back to the built-in WebAudio analyzer when FFmpeg is not installed.
  • Deck analysis therefore works without requiring the user to install FFmpeg.

ffmpeg

  • Uses FFmpeg loudnorm for the most accurate full-file analysis.
  • If FFmpeg is missing and the current platform is supported, the panel offers Install FFmpeg.
  • The add-on never silently installs software; installation starts only after an explicit click.

webaudio / Built-in (no FFmpeg)

  • Does not require an external FFmpeg executable.
  • Uses Qt WebEngine's WebAudio decoder for common audio formats supported by the Anki webview.
  • Uses 400 ms analysis blocks, gated RMS measurement and a peak safety calculation.
  • The result is intentionally marked as approximate because WebAudio does not expose FFmpeg's full EBU R128/true-peak implementation.
  • It is intended to provide useful deck-wide balancing when the user does not want to install FFmpeg.
  • Files larger than 64 MB are rejected by the built-in analyzer to avoid excessive memory use.

Optional FFmpeg installation

When FFmpeg is missing and the platform is supported, the panel displays Install FFmpeg.

The add-on downloads a pinned imageio-ffmpeg platform package and extracts only its FFmpeg executable into the add-on's persistent user_files directory:

user_files/tools/ffmpeg/

This does not require administrator/root privileges and does not replace the system FFmpeg.

Security rules used by the installer:

  • installation only starts after an explicit user click;
  • download URLs are fixed in the source code and use HTTPS;
  • the expected platform, file size and SHA-256 are pinned;
  • redirects to untrusted hosts are rejected;
  • only the expected FFmpeg binary is extracted;
  • the extracted executable is validated before being used;
  • external processes use argument arrays with shell=False;
  • failure never blocks normal Anki playback;
  • the built-in analyzer remains available if installation is declined or fails.

Supported managed-download targets currently include Windows x86-64, Linux x86-64, Linux ARM64, macOS Intel and macOS Apple Silicon.

Analyze deck workflow

  1. Open a card from the deck.
  2. Choose an analysis method, or leave Automatic selected.
  3. Click Analyze deck.
  4. The add-on finds all audio files used by that deck.
  5. Each file is measured with FFmpeg or the built-in analyzer.
  6. A gain is calculated while respecting the configured target and peak safety.
  7. The profile is saved and Use analyzed profile is enabled.
  8. Study normally; the gain is applied only during playback.

Reanalyze after replacing/adding audio, changing the target LUFS, or changing dual-mono behavior.

Configuration

{
  "language": "auto",
  "normalize": true,
  "loudness_target": -24,
  "dual_mono": false,
  "speed": 1.0,
  "volume": 1.0,
  "deck_profile_enabled": false,
  "analysis_backend": "auto"
}

Build

python3 build.py

The package is created in dist/ and contains only runtime add-on files. Tests, local user profiles and caches are excluded.

Tests

Python tests:

python -m unittest tests.test_analysis_engine -v

Playwright reviewer UI tests:

python tests/test_audio_controller_playwright.py -v

The Playwright suite covers analysis controls, FFmpeg state, the built-in loudness measurement, path traversal rejection and panel minimize/expand behavior.


Português (Brasil)

Idiomas

Idiomas suportados:

  • English (en)
  • Português do Brasil (pt-BR)

Configuração padrão:

"language": "auto"

auto detecta o locale do sistema operacional. Locales em português usam pt-BR; idiomas ainda não suportados usam inglês como fallback.

Para alterar, abra Ferramentas → Extensões/Add-ons → Balanced Audio Controller → Configuração/Config e defina language como auto, en ou pt-BR.

Controles de reprodução

  • Velocidade: 0,25x até 2,0x, padrão 1,0x.
  • − e + alteram a velocidade em 0,5x.
  • É possível informar a velocidade manualmente.
  • Volume: 0% até 100%.
  • Os botões originais de play/replay do Anki permanecem nativos.
  • O painel é arrastável; dois cliques na barra de título restauram a posição padrão.
  • O botão − na barra de título minimiza o add-on deixando apenas a barra superior. Minimizado, o botão muda para + para expandir novamente.
  • O estado minimizado/expandido é salvo localmente e restaurado nos próximos cartões.

Normalização em tempo real

Quando ativada, a extensão aplica loudnorm pelo player MPV do Anki durante a reprodução.

  • Loudness alvo: -50 até -20 LUFS.
  • Padrão: -24 LUFS.
  • Limite de true peak: -1,5 dBTP.
  • LRA alvo: 7 LU.
  • Compensação dual-mono opcional para gravações mono reproduzidas em saída estéreo.

Esse modo não exige o executável externo ffmpeg, pois utiliza os filtros disponíveis pelo próprio Anki/MPV.

Perfil de análise do deck

O perfil do deck analisa cada arquivo de áudio e salva somente o ganho calculado. Os arquivos originais do deck nunca são sobrescritos ou recodificados.

O perfil fica em:

user_files/deck_profiles.json

Ele continua salvo depois de fechar o Anki ou reiniciar o computador.

Métodos de análise

A extensão possui três modos em analysis_backend:

auto
ffmpeg
webaudio

auto (recomendado)

  • Usa o FFmpeg externo quando ele está disponível.
  • Caso o FFmpeg não esteja instalado, usa automaticamente o analisador WebAudio interno.
  • Portanto, Analisar deck funciona mesmo sem instalar FFmpeg.

ffmpeg

  • Usa loudnorm do FFmpeg para a análise completa mais precisa.
  • Se o FFmpeg não existir e a plataforma for suportada, o painel oferece Instalar FFmpeg.
  • A extensão nunca instala programas silenciosamente: a instalação só começa após um clique explícito do usuário.

webaudio / Interno (sem FFmpeg)

  • Não exige um executável FFmpeg externo.
  • Usa o decodificador WebAudio do Qt WebEngine para os formatos aceitos pela webview do Anki.
  • Usa blocos de 400 ms, medição RMS com gate e cálculo de segurança de pico.
  • A medição é identificada como aproximada, pois o WebAudio não oferece a implementação completa de EBU R128/true peak do FFmpeg.
  • É indicado para equilibrar o deck quando o usuário não deseja instalar FFmpeg.
  • Arquivos acima de 64 MB são rejeitados pelo analisador interno para evitar uso excessivo de memória.

Instalação opcional do FFmpeg

Quando o FFmpeg não está disponível e a plataforma é suportada, o painel mostra Instalar FFmpeg.

A extensão baixa um pacote de plataforma fixado do imageio-ffmpeg e extrai somente o executável FFmpeg para a pasta persistente do add-on:

user_files/tools/ffmpeg/

Isso não exige administrador/root e não substitui o FFmpeg instalado no sistema.

Regras de segurança da instalação:

  • só inicia após clique explícito do usuário;
  • URLs de download são fixas no código e usam HTTPS;
  • plataforma, tamanho esperado e SHA-256 são fixados;
  • redirecionamentos para hosts não confiáveis são rejeitados;
  • somente o binário esperado do FFmpeg é extraído;
  • o executável extraído é validado antes de ser usado;
  • processos externos usam lista de argumentos e shell=False;
  • uma falha nunca impede a reprodução normal do Anki;
  • o analisador interno continua disponível se o usuário recusar ou se a instalação falhar.

Os downloads gerenciados atualmente suportam Windows x86-64, Linux x86-64, Linux ARM64, macOS Intel e macOS Apple Silicon.

Fluxo de Analisar deck

  1. Abra um cartão do deck.
  2. Escolha o método de análise ou mantenha Automático.
  3. Clique em Analisar deck.
  4. A extensão localiza os áudios utilizados pelo deck.
  5. Cada arquivo é medido pelo FFmpeg ou pelo mecanismo interno.
  6. O ganho é calculado respeitando o alvo e a margem de pico.
  7. O perfil é salvo e Usar perfil analisado é ativado.
  8. Estude normalmente; o ganho é aplicado somente durante a reprodução.

Reanalise depois de adicionar/substituir áudios, alterar o LUFS alvo ou alterar a opção dual-mono.

Configuração

{
  "language": "auto",
  "normalize": true,
  "loudness_target": -24,
  "dual_mono": false,
  "speed": 1.0,
  "volume": 1.0,
  "deck_profile_enabled": false,
  "analysis_backend": "auto"
}

Build

python3 build.py

O pacote é criado em dist/ contendo somente os arquivos necessários em runtime. Testes, perfis locais e caches não são incluídos.

Testes

Testes Python:

python -m unittest tests.test_analysis_engine -v

Testes Playwright da interface do revisor:

python tests/test_audio_controller_playwright.py -v

A suíte Playwright valida controles de análise, estado do FFmpeg, medição interna de loudness, rejeição de path traversal e o comportamento de minimizar/expandir o painel.

License / Licença

MIT License.

Compact reviewer panel / Painel compacto no revisor

The reviewer panel intentionally keeps only the controls used while studying: speed, volume, real-time normalization, deck-profile status and Analyze deck. Advanced options and maintenance actions are available under Tools → Balanced Audio Controller → Settings.

O painel do revisor mantém somente os controles usados durante o estudo: velocidade, volume, normalização em tempo real, status do perfil e Analisar deck. As opções avançadas e ações de manutenção ficam em Ferramentas → Balanced Audio Controller → Configurações.

Materialized normalized audio / Áudio normalizado materializado

After a deck has been analyzed, Create normalized copies / Criar cópias normalizadas can render a second, already-normalized audio file for each analyzed source. This operation requires FFmpeg because it writes real audio files; the built-in WebAudio analyzer remains available for analysis only.

The original media is never overwritten. Generated files use a deterministic bac_norm_... name and are imported through Anki's media manager. The add-on creates a dedicated BAC Áudio Normalizado note field (or a numbered alternative if that name is already used by unrelated content), writes native [sound:...] references into it, and can automatically add that field to the same template side (front or back) where the original audio field is used. A separate Create audio field + update card HTML action prepares the field/template even before physical audio copies are generated.

Depois que o deck for analisado, Criar cópias normalizadas pode gerar um segundo arquivo de áudio já normalizado para cada áudio analisado. Essa operação exige FFmpeg porque grava arquivos de áudio reais; o analisador WebAudio interno continua disponível para análise sem FFmpeg.

A mídia original nunca é sobrescrita. Os arquivos gerados usam nomes determinísticos bac_norm_... e são importados pelo gerenciador de mídia do Anki. O add-on cria um campo dedicado BAC Áudio Normalizado na nota (ou uma alternativa numerada caso esse nome já contenha dados não relacionados), grava referências nativas [sound:...] nele e pode inserir automaticamente esse campo na mesma face do template (frente ou verso) em que o áudio original é usado. A ação separada Criar campo de áudio + atualizar HTML prepara o campo/template mesmo antes de gerar as cópias físicas.