Добавлена фильтрация по приложению, реальный контекст происхождения, списки с навигацией по столбцам, настройки с вкладками, объяснение на человеческом языке, свободное сравнение
кадров, симуляция других размеров, маршрутизация и симулированный ввод с брайлевской
клавиатуры, а также опциональное непрерывное журналирование.

Virtual Braille Display 2026.08.30

Дополнение NVDA, которое регистрируется как дополнительная брайлевская строка и сохраняет, байт за байтом, то, что NVDA передаёт в display(cells). Оно позволяет узнать, что получила бы реальная брайлевская строка без её наличия, а также проверить, предоставляет ли приложение полезную информацию в брайле.

Автор: Héctor J. Benítez Corredera · Лицензия: GNU GPL версии 2 или более поздней

Содержание

1. Что делает
2. Требования и установка
3. Первые шаги
4. Подменю «Сервис»
5. Назначаемые жесты
6. Просмотрщик
7. Простое объяснение
8. Фильтрация по приложению
9. Навигация по спискам
10. Настройки
11. Конфиденциальность и журналирование
12. Тестирование со сторонними приложениями
13. Происхождение и достоверность
14. Переводы
15. Разработка
16. Частые проблемы
17. Ограничения и план развития

Что делает

Захватывает два уровня информации и никогда их не смешивает:

Каждый кадр также сохраняет контекст , считанный из самого NVDA непосредственно перед записью: какой буфер его сгенерировал (навигационный или сообщение), к чему привязана строка, а также процесс, приложение, имя и роль объекта, который в этот момент отображался.

Никогда не восстанавливает брайль из голоса, не использует OCR, не предполагает, что сфокусированный процесс является вызвавшим Controller Client, и не выдумывает PID.

Требования и установка

Требуется Windows и NVDA 2026.1 или новее (работает с единственным модулем braille в 2026.1 и с реорганизованным пакетом в 2026.3). Не требует внешних библиотек. Примеры требуют Python 3, accessible-output2 и wxPython.

1. Откройте virtualBrailleDisplay-2026.08.30.nvda-addon и подтвердите установку.
2. Перезапустите NVDA.
3. В настройках брайля NVDA выберите Virtual Braille Display в качестве брайлевской строки.

Первые шаги

1. Назначьте жест команде Открыть просмотрщик с фильтром по приложению в фокусе в Параметры > Жесты ввода > Virtual Braille Display.
2. Переведите фокус на приложение, которое хотите проверить, и нажмите этот жест: дополнение захватывает его PID и открывает просмотрщик, показывая только то, что создаёт это приложение.
3. Используйте приложение как обычно; кадры будут появляться в истории.
4. Если вы не читаете брайль, нажмите Простое объяснение — вы получите те же данные, изложенные на простом русском языке.

Подменю «Сервис»

Всё сгруппировано в NVDA > Сервис > Virtual Braille Display:

Две детали, чтобы меню действительно работало:

• Фильтр правильно определяет приложение. При открытии меню фокус переходит на само меню, которое принадлежит NVDA. Дополнение отбрасывает этот PID и использует gui.mainFrame.prevFocus — объект, который NVDA сохраняет при открытии меню; это именно то приложение, из которого вы его открыли.
• Сообщения не теряются. ui.message, отправленное при закрытии меню, отменяется объявлением окна, возвращающего фокус. Сообщения меню используют ui.delayedMessage — функцию, которую NVDA предлагает для подтверждения действий меню. Если вы предпочитаете не полагаться на голос, в Настройках можно включить отображение диалогового окна.

Назначаемые жесты

В Параметры > Жесты ввода, категория Virtual Braille Display. Ни один из них не имеет назначенной клавиши по умолчанию.

Просмотрщик

Начинается с сводки состояния , доступной через Tab: подключение, геометрия, режим просмотрщика, активный фильтр и количество кадров и событий. Под ней — семь вкладок:

Кнопки: Подключить , Отключить , Приостановить обновления (только интерфейса; захват продолжается), Зафиксировать отображаемый кадр , Обновить сейчас , Фильтровать по приложению в фокусе , Убрать фильтр , Простое объяснение , Копировать , Сохранить… , Очистить , Настройки… и Закрыть.

Пока просмотрщик в фокусе, он не обновляется автоматически, чтобы не создавать цикл между его собственной доступностью и выводом в брайль. Используйте Обновить сейчас для загрузки снимка.

Простое объяснение

Окно, предназначенное для тех, кто видит, не знает брайль и хочет сделать своё приложение доступным. Показывает, какой текст читал бы пользователь брайлевской строки, откуда он берётся, из какого приложения и сколько места занимает; а под ним — автоматический анализ:

Скопировать отчёт помещает весь текст в буфер обмена.

Фильтрация по приложению

Позволяет видеть только то, что создаёт ваша программа. Есть три способа: жест клавиатуры (лучший, потому что фокус всё ещё находится в вашем приложении), подменю «Сервис» и раскрывающийся список Показывать только приложение в истории кадров.

Фильтр сравнивает два реальных данных, никогда не предположение: PID контекста кадра и PID, подтверждённый через RPC коррелированным внешним событием. Он влияет на историю, сравнение, статистику, экспорт и простое объяснение, но не изменяет происхождение и достоверность ни одного кадра: это решение об отображении.

Кнопка Фильтровать по приложению в фокусе внутри просмотрщика предупреждает, если не может определить приложение, потому что с открытым просмотрщиком фокус находится на самом просмотрщике.

Навигация по спискам

NVDA читает целую строку с помощью стрелок вверх и вниз. Дополнение добавляет перемещение от ячейки к ячейке:

Объявления используют ui.message — собственную функцию NVDA, которая одновременно говорит и отправляет текст на брайлевскую строку; никакие внешние библиотеки не задействованы. Списки хранят полный текст каждой ячейки, потому что нативный элемент управления Windows обрезает его примерно до 511 символов.

Настройки

Шесть вкладок. Все элементы управления создаются с помощью gui.guiHelper, который помещает метку перед элементом управления; именно такой порядок нужен экранному диктофу, чтобы озвучивать имя поля вместе с его значением.

Если вы отключите все опции озвучивания столбцов, содержимое ячейки всё равно будет произноситься, чтобы навигация не оставалась беззвучной.

Конфиденциальность и журналирование

Брайль, получаемый строкой, может содержать пароли, документы, сообщения и уведомления.

• Истории хранятся только в памяти и исчезают при закрытии NVDA.
• На диск автоматически ничего не записывается.
• Сохранить… экспортирует снимок в TXT, JSON или JSONL в кодировке UTF-8 после явного предупреждения. В JSONL каждая запись содержит поле type со значением frame или externalEvent.
• Непрерывное журналирование по умолчанию отключено. При активации оно пишет в отдельном потоке с ограниченной очередью: display(cells) только помещает запись в журнал и продолжает работу. Если диск не успевает, записи отбрасываются с подсчётом, прежде чем замедлить NVDA.

Включайте его во время отладки и отключайте после.

Тестирование со сторонними приложениями

Работает с уже существующими приложениями без их модификации:

output = Auto() output.braille("Загрузка завершена") ```

Путь: приложение вызывает `nvdaController_brailleMessage` в DLL Controller
Client → RPC → `NVDAHelper` ставит в очередь `BrailleHandler.message(text)` →
`TextRegion` и liblouis → `_writeCells` уведомляет `pre_writeCells` →
`display(cells)` в виртуальной строке.

В папке `examples/` есть две программы, которые запускаются **вне** NVDA:
`test_accessible_output2.py`, которая проверяет, активен ли NVDA, и позволяет
повторять сообщения, и `wx_test_app.py` — приложение wxPython с кнопками для
отправки в голос и брайль или только в брайль. В проанализированной версии
`accessible_output2` `Auto.output` только говорит; поэтому в примерах явно
вызывается `braille(text)`.

## Происхождение и достоверность

Каждый кадр содержит происхождение и уровень достоверности:

Происхождение | Когда используется  
---|---  
`NVDA_NAVIGATION` | Активным буфером был основной и имел видимые области.  
`BRAILLE_MESSAGE` | Активным буфером был буфер сообщений NVDA.  
`CORRELATED_EXTERNAL_MESSAGE` | Был сопоставлен с внешним запросом.  
`UNKNOWN` | NVDA не предоставил достаточного контекста.  
Достоверность | Что именно означает  
---|---  
`CONFIRMED` | Личность буфера NVDA проверяема. Подтверждает, **какая часть NVDA** создала ячейки, но никогда не подтверждает, какое приложение запросило сообщение.  
`PROBABLE` | Корреляция по тексту и времени с внешним запросом.  
`CONTEXT` | Есть только контекст; происхождение не приписывается.  
`UNKNOWN` | Не определено.  

**Ключевое различие.** Просмотрщик показывает два разных приложения и никогда
их не путает:

  * _Приложение, содержимое которого отображалось_ : контекст, полученный из `region.obj`. Отвечает на вопрос «кому принадлежит отображаемый текст».
  * _Запрашивающее приложение_ : PID, подтверждённый с помощью `I_RpcBindingInqLocalClientPID` во время обработки вызова RPC. Отвечает на вопрос «кто вызвал `nvdaController_brailleMessage`».

NVDA не передаёт личность RPC-клиента вплоть до `display(cells)`. Поэтому
личность события подтверждена, но его связь с последующим кадром является, в
лучшем случае, вероятной. Полная информация — в [`docs/origin-
tracking.md`](docs/origin-tracking.md).

## Переводы

Дополнение написано на испанском и поддерживает переводы на любые языки.
Важно: **переводы и документация распространяются отдельно от дополнения** в
виде отдельного релиза ресурсов, чтобы они попадали к пользователю без
установки новой версии.

**Если вы хотите перевести его:** возьмите `virtualBrailleDisplay.pot` из
корня репозитория или уже готовый шаблон в
`addon/locale/en/LC_MESSAGES/nvda.po`. Создайте
`addon/locale/{язык}/LC_MESSAGES/nvda.po` и отправьте его. Компилировать
ничего не нужно.

**Что происходит потом:** при объединении файла GitHub Action компилирует
`.po`, генерирует переведённый `manifest.ini` и документацию в HTML,
упаковывает всё и публикует в релизе ресурсов. Принять перевод — значит просто
объединить один файл.

**Если вы используете дополнение:** оно проверяет наличие новых ресурсов при
запуске NVDA, не чаще одного раза в день. Вы можете изменить это или отключить
в **Настройки > Обновления**, а также проверить вручную через **Сервис >
Virtual Braille Display > Искать новые переводы и документацию**. Загружаются
только переводы и документация — никогда код.

Тег релиза ресурсов вычисляется автоматически из версии дополнения: для
`2026.08.30` это `recursos_2026.08`. GitHub Action и дополнение используют
одно и то же правило, и это правило покрыто тестами, поэтому рассинхронизация
невозможна.

Полная информация, включая что нужно знать при переводе, находится в
[`docs/traducciones.md`](docs/traducciones.md).

## Разработка

Код находится в `addon/globalPlugins/virtualBrailleDisplay/`, драйвер отдельно
в `addon/brailleDisplayDrivers/virtualBraille.py`. У каждого модуля своя
ответственность: захват и хранилище (`runtime`, `frameStore`,
`contextTracker`, `originTracker`, `controllerTracker`), преобразование и
объяснение (`brailleUtils`, `brailleDecoder`, `diagnostics`, `frameText`),
интерфейс (`gui`, `simpleView`, `settingsDialog`, `accessibleList`,
`guiUtils`, `messages`) и поддержка (`config`, `models`, `logWriter`,
`gestures`, `nvdaCompat`) и обновление ресурсов (`resourceUpdates`, а также
`actualizadorRecursos` без изменений).

Сборка и очистка с помощью `scons -c`:

`bash scons`

Тесты, не требующие NVDA:

`bash python -m pytest tests -q`

Стиль:

`bash python -m ruff check .`

Техническая документация: [`docs/architecture.md`](docs/architecture.md)
(реальный поток и используемые API NVDA), [`docs/origin-
tracking.md`](docs/origin-tracking.md) (что известно, что нет и где теряется)
и [`docs/traducciones.md`](docs/traducciones.md) (полный процесс перевода) и
[`docs/testing.md`](docs/testing.md) (автоматические тесты и 45 ручных
сценариев).

## Частые проблемы

Симптом | Что проверить  
---|---  
Не появляется ни одного кадра | Убедитесь, что **Virtual Braille Display** выбран в настройках брайля и в сводке состояния сказано «Строка подключена».  
Фильтр ничего не показывает | Вероятно, был захвачен PID просмотрщика. Нажмите _Убрать фильтр_ и захватите снова жестом из вашего приложения.  
Внешние события не поступают | NVDA запущен, `accessible_output2` его обнаруживает, брайлевские сообщения активированы и явно вызывается `braille(text)`. Если NVDA пишет «API interna ausente», хук не удалось установить в этой версии; захват кадров продолжает работать.  
Маршрутизация или аккорд не работают | Требуется подключённая виртуальная строка.  
Теряется сообщение из меню | Такого не должно происходить: они используют `ui.delayedMessage`. Если это случается, включите диалоговое окно в _Списки и уведомления_.  
NVDA не озвучивает имя поля | Это ошибка, а не ограничение: сообщите о ней.  

## Ограничения и план развития

  * Обратный перевод, предлагаемый, когда NVDA не предоставляет текст, является **приблизительным** и всегда помечается как таковой; он никогда не заменяет ячейки.
  * Связь между внешним запросом и кадром является, в лучшем случае, **вероятной**.
  * PID контекста идентифицирует приложение, содержимое которого отображалось, но не обязательно приложение, запросившее сообщение.
  * Хук Controller Client использует внутренний API NVDA. Если он изменится, отключится только история внешних событий.
  * Виртуального HID-устройства нет: строка существует внутри NVDA.

В планах: кооперативный протокол через локальный IPC, позволяющий приложению
сообщать свой PID и идентификатор корреляции перед вызовом Controller Client,
что сделает атрибуцию подтверждённой; вспомогательный модуль
`virtual_braille_debug`; и исследование виртуального HID Braille-устройства
для Windows.