8000 Add a home screen audio player widget by AhmedEljanady · Pull Request #4000 · quran/quran_android · GitHub
[go: up one dir, main page]
Skip to content

Add a home screen audio player widget - #4000

Open
AhmedEljanady wants to merge 1 commit into
quran:mainfrom
AhmedEljanady:feature/audio-player-widget
Open

Add a home screen audio player widget#4000
AhmedEljanady wants to merge 1 commit into
quran:mainfrom
AhmedEljanady:feature/audio-player-widget

Conversation

@AhmedEljanady
@AhmedEljanady AhmedEljanady commented Nov 3, 2026
Copy link
Copy Markdown

Closes #3999

What this adds

A "Quran Audio Player" home screen widget that plays a chosen range of verses with a chosen reciter, independently of the reader.

  • Settings: adding the widget opens AudioWidgetConfigureActivity. It offers:

    • an optional title
    • a reciter
    • From and To sura/ayah, where the ayah list follows the chosen sura
    • repeat the set of verses and repeat each verse, both including infinite
    • playback speed
    • "Only play the above verses"

    Cancelling removes the widget. Tapping the widget's text reopens the settings, since the widget is reconfigurable.

  • Several widgets: settings are stored per appWidgetId in their own preferences file and removed when the widget is deleted.

  • Layout: a single row, 4×1 by default and resizable. It shows an app icon that opens the app, the title (or the sura name), the reciter, the live status (Loading / Playing / Paused with the current ayah), and Previous / Play-Pause / Next.

  • Preview: a previewLayout for Android 12+ and a previewImage for older versions.

  • Translations: the widget strings are added in all 28 languages the app ships.

Keeping the reader separate

The reader's ayah highlighting, page following and audio bar all come from AudioStatusRepository.

  • When playback starts from a widget, AudioService keeps the widget's id. Until something else starts playback, it publishes AudioStatus.Stopped to the repository and sends the real status only to the widget, through AudioWidgetUpdater.
  • So widget playback never turns pages, never highlights ayahs, never shows the audio bar and never moves the last-read position.

Related changes in AudioService:

  • A new ACTION_WIDGET_PLAYBACK builds the AudioRequest from the widget's saved settings in AudioWidgetRequestFactory.
    • It uses downloaded files when every file is present and streams otherwise, since a widget can't show the download prompt.
    • If a gapless reciter's timing database is missing, the widget starts that download and shows "Downloading required files…".
  • Starting playback from the app takes over from the widget, because there is still only one player.
  • While the widget is playing, tapping the notification opens the last-read page instead of the reader.
  • QuranActivity sends ACTION_STOP on resume to clean up leftover playback. It now passes EXTRA_KEEP_WIDGET_PLAYBACK, so opening the app doesn't stop the widget's audio. The notification's Stop button still stops it.

Testing

Manually on an Android 16 emulator (Pixel 9 Pro XL):

  • The widget shows in the widget list with its preview, and the settings screen opens on add. Cancelling removes the widget.
  • Play / Pause / Next / Previous, and the status updates while playing.
  • Playback continues across suras within the range, both streaming and from downloaded files.
  • With the reader open on An-Nisa (page 77) while the widget plays Al-Fatihah: the page doesn't change, nothing is highlighted, and the audio bar stays idle.
  • Opening the app from cold doesn't stop widget playback.
  • The app icon on the widget opens the app.
  • Arabic UI: the strings show, and the media controls keep their order in right-to-left layouts.
  • Not tested: a gapless reciter whose timing database isn't downloaded yet.

Automated:

  • AudioWidgetPreferencesTest (Robolectric) covers round-tripping settings, isolation between widgets, reconfiguring, and deleting one widget without touching another, for example ids 1 and 11.
  • assembleMadaniDebug and lintMadaniDebug pass.
  • I couldn't run the unit tests locally because the project needs JDK 27 and I have 21, so I'm relying on CI for them.

Screenshots

Widget list Settings Playing Reader unaffected
1-widget-picker.png 2-settings.png 3-widget-playing.png 5-reader-untouched.png
< 8000 /markdown-accessiblity-table>

Notes for review

  • The translations were drafted with AI help. Native speakers should check them, and I can drop them if you'd rather they go through your translators.
  • In right-to-left layouts the media controls are pinned left-to-right (layoutDirection="ltr"), like other media players.
  • android:tint is kept on the widget's buttons, with UseAppTint suppressed, because app:tint doesn't work in RemoteViews.

🤖 Generated with Claude Code

@AhmedEljanady @claude
Add a home screen audio player widget
65fdda0 
Adds a configurable "Quran Audio Player" widget that plays a chosen range
of verses with a chosen reciter, repeat count, and playback speed. Each
widget keeps its own settings, and the widget shows the title, reciter,
and live playback status with previous, play/pause, and next controls.

Widget playback is independent of the reader: while a widget is playing,
the reader is not sent its playback status, so it does not highlight
ayahs, change pages, update the last read position, or show the audio bar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AhmedEljanady
AhmedEljanady commented Nov 3, 2026
Copy link
Copy Markdown
Author
1-widget-picker 2-settings 3-widget-playing 4-widget-arabic 5-reader-untouched

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Home screen audio player widget

1 participant

@AhmedEljanady
0