feat(mac/v2): expose mediaTypesRequiringUserActionForPlayback on WKWebView#5512
Open
Eyalm321 wants to merge 3 commits into
Open
feat(mac/v2): expose mediaTypesRequiringUserActionForPlayback on WKWebView#5512Eyalm321 wants to merge 3 commits into
Eyalm321 wants to merge 3 commits into
Conversation
Contributor
WalkthroughThis PR adds macOS media autoplay support to Wails v2 by introducing a new user-facing preference, bridging it through C to Objective‑C, and applying it directly to WebKit's audio/visual media configuration during window creation. ChangesmacOS Media Autoplay Feature
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
3 tasks
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
.github/workflows/build-macos-media-playback.yml (1)
18-23: ⚖️ Poor tradeoffConsider pinning actions to commit SHAs.
Pinning to commit hashes prevents supply-chain attacks via tag/version manipulation.
Example with SHA pinning
- - uses: actions/checkout@v4 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: persist-credentials: false - - uses: actions/setup-go@v5 + - uses: actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a # v5.2.0You can find the commit SHAs for specific versions in each action's repository release page.
Also applies to: 43-48
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/build-macos-media-playback.yml around lines 18 - 23, Replace floating action tags with immutable commit SHAs: locate the occurrences of "uses: actions/checkout@v4" and "uses: actions/setup-go@v4" (and the other occurrences flagged around lines 43-48) and change them to the corresponding commit SHA references from each action's GitHub repo (e.g., actions/checkout@<commit-sha> and actions/setup-go@<commit-sha>); update the workflow comments to note the chosen SHAs and, if desired, add a short note or workflow-level variable that documents the original tag version for future updates.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/build-macos-media-playback.yml:
- Line 20: Replace the outdated runner reference "uses: actions/setup-go@v4"
with "uses: actions/setup-go@v5" wherever it appears in the workflow (there are
two occurrences of the literal "uses: actions/setup-go@v4"); update both
instances so the workflow uses actions/setup-go@v5.
- Line 18: Update the checkout steps that use the action identifier "uses:
actions/checkout@v4" to include the option persist-credentials: false so
credentials are not persisted in the workspace; apply this change to each
checkout step occurrence (including the second occurrence referenced in the
review) by adding the persist-credentials: false key under the same job/step
that calls actions/checkout@v4.
- Around line 1-9: Add an explicit top-level GitHub Actions permissions block
for the "Build darwin (media-playback options)" workflow (the YAML with the
name: Build darwin (media-playback options) and the on: section) to restrict the
OIDC token scope; include only the minimal required permissions such as
contents: read and packages: read (and add id-token: write only if the workflow
needs OIDC), placing the permissions stanza at the top-level of the workflow
file.
---
Nitpick comments:
In @.github/workflows/build-macos-media-playback.yml:
- Around line 18-23: Replace floating action tags with immutable commit SHAs:
locate the occurrences of "uses: actions/checkout@v4" and "uses:
actions/setup-go@v4" (and the other occurrences flagged around lines 43-48) and
change them to the corresponding commit SHA references from each action's GitHub
repo (e.g., actions/checkout@<commit-sha> and actions/setup-go@<commit-sha>);
update the workflow comments to note the chosen SHAs and, if desired, add a
short note or workflow-level variable that documents the original tag version
for future updates.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 85a2b43e-54c3-4dce-a8e9-db080071f2e3
📒 Files selected for processing (5)
.github/workflows/build-macos-media-playback.ymlv2/internal/frontend/desktop/darwin/WailsContext.hv2/internal/frontend/desktop/darwin/WailsContext.mv2/internal/frontend/desktop/darwin/window.gov2/pkg/options/mac/preferences.go
Eyalm321
force-pushed
the
fix/macos-media-playback-options-v2
branch
from
20bd946 to
bf58079
Compare
Add EnableAutoplayWithoutUserAction to mac.Preferences, mapping to WKWebViewConfiguration.mediaTypesRequiringUserActionForPlayback. Without this option, there is no way to autoplay HTML5 video/audio in a Wails v2 macOS app — every <video autoplay> is blocked by WebKit's user-gesture requirement. Follows the existing pattern used for TabFocusesLinks, FullscreenEnabled etc.: u.Bool option, bool* in the C struct, applied on WKWebViewConfiguration when set. Defaults preserve current WebKit behaviour (gesture required) — opt-in only. iOS already exposes the equivalent (EnableAutoplayWithoutUserAction in v3 application_options.go); this brings v2 macOS to parity. Closes wailsapp#5511
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (3)
.github/workflows/build-macos-media-playback.yml (3)
20-20:⚠️ Potential issue | 🔴 Critical | ⚡ Quick win
actions/setup-go@v4is outdated and can fail the workflow.At Line 20 and Line 45, bump to
actions/setup-go@v5.Suggested patch
- - uses: actions/setup-go@v4 + - uses: actions/setup-go@v5 ... - - uses: actions/setup-go@v4 + - uses: actions/setup-go@v5Also applies to: 45-45
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/build-macos-media-playback.yml at line 20, Replace the outdated GitHub Actions step using actions/setup-go@v4 with actions/setup-go@v5 in the workflow file: locate the occurrences of the runner step that reads "uses: actions/setup-go@v4" (found at the instances around the top-level steps, including the lines referenced) and update the version tag to "actions/setup-go@v5" for both occurrences so the workflow uses the current setup-go action.
18-18:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDisable credential persistence on checkout.
At Line 18 and Line 43, set
persist-credentials: falseto reduce token exposure across later steps/artifacts.Suggested patch
- uses: actions/checkout@v4 + with: + persist-credentials: false ... - uses: actions/checkout@v4 + with: + persist-credentials: falseAlso applies to: 43-43
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/build-macos-media-playback.yml at line 18, Update the GitHub Actions checkout steps to disable credential persistence by adding persist-credentials: false to each actions/checkout@v4 invocation; specifically modify the checkout step(s) referenced (the steps that call actions/checkout@v4 at both occurrences) to include the persist-credentials: false key so tokens are not automatically persisted to later steps or artifacts.
1-9:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd least-privilege workflow permissions.
There is no top-level
permissionsblock, so the workflow inherits broader defaults. Add minimal read-only scope unless a job explicitly needs more.Suggested patch
name: Build darwin (media-playback options) +permissions: + contents: read + on:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/build-macos-media-playback.yml around lines 1 - 9, Add a top-level GitHub Actions permissions block to this workflow (name "Build darwin (media-playback options)") to enforce least-privilege access by setting minimal read-only scopes (e.g., set contents: read) at the root of the YAML; if any job or step (refer to job names in this workflow) requires broader rights, grant only the specific additional permissions on that job via its own permissions map.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In @.github/workflows/build-macos-media-playback.yml:
- Line 20: Replace the outdated GitHub Actions step using actions/setup-go@v4
with actions/setup-go@v5 in the workflow file: locate the occurrences of the
runner step that reads "uses: actions/setup-go@v4" (found at the instances
around the top-level steps, including the lines referenced) and update the
version tag to "actions/setup-go@v5" for both occurrences so the workflow uses
the current setup-go action.
- Line 18: Update the GitHub Actions checkout steps to disable credential
persistence by adding persist-credentials: false to each actions/checkout@v4
invocation; specifically modify the checkout step(s) referenced (the steps that
call actions/checkout@v4 at both occurrences) to include the
persist-credentials: false key so tokens are not automatically persisted to
later steps or artifacts.
- Around line 1-9: Add a top-level GitHub Actions permissions block to this
workflow (name "Build darwin (media-playback options)") to enforce
least-privilege access by setting minimal read-only scopes (e.g., set contents:
read) at the root of the YAML; if any job or step (refer to job names in this
workflow) requires broader rights, grant only the specific additional
permissions on that job via its own permissions map.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 01eaee00-77e6-49e6-bf80-f93f014163cc
📒 Files selected for processing (5)
.github/workflows/build-macos-media-playback.ymlv2/internal/frontend/desktop/darwin/WailsContext.hv2/internal/frontend/desktop/darwin/WailsContext.mv2/internal/frontend/desktop/darwin/window.gov2/pkg/options/mac/preferences.go
✅ Files skipped from review due to trivial changes (1)
- v2/internal/frontend/desktop/darwin/WailsContext.h
🚧 Files skipped from review as they are similar to previous changes (3)
- v2/internal/frontend/desktop/darwin/window.go
- v2/pkg/options/mac/preferences.go
- v2/internal/frontend/desktop/darwin/WailsContext.m
Eyalm321
force-pushed
the
fix/macos-media-playback-options-v2
branch
from
bf58079 to
f39b362
Compare
Eyalm321
pushed a commit
to Eyalm321/clawdpanel
that referenced
this pull request
May 27, 2026
Pin to a Wails v2 fork that exposes WKWebViewConfiguration.mediaTypesRequiringUserActionForPlayback, then opt in via Mac.Preferences.EnableAutoplayWithoutUserAction. Without this, every <video>/<audio> tag in the embedded webview required a click before playback — making things like ambient bar audio unusable. Fork: github.com/Eyalm321/wails/v2 v2.12.0-mediaplayback.1 Upstream PR: wailsapp/wails#5512 Bumps CI Go to 1.25 to match the fork's go.mod requirement. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Eyalm321
added a commit
to Eyalm321/clawdpanel
that referenced
this pull request
May 28, 2026
Pin to a Wails v2 fork that exposes WKWebViewConfiguration.mediaTypesRequiringUserActionForPlayback, then opt in via Mac.Preferences.EnableAutoplayWithoutUserAction. Without this, every <video>/<audio> tag in the embedded webview required a click before playback — making things like ambient bar audio unusable. Fork: github.com/Eyalm321/wails/v2 v2.12.0-mediaplayback.1 Upstream PR: wailsapp/wails#5512 Bumps CI Go to 1.25 to match the fork's go.mod requirement. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Member
|
Thanks for this — the implementation looks good! Before we merge, could you add two things:
We'll handle v3 support in a separate follow-up PR once this lands. |
Member
|
v3 support has been implemented on branch
This will be merged alongside (or shortly after) this PR. |
3 tasks
…g entry Addresses review feedback on wailsapp#5512: - Add EnableAutoplayWithoutUserAction row to the MacWebviewPreferences table in website/docs/reference/options.mdx (with Apple docs link for WKWebViewConfiguration.mediaTypesRequiringUserActionForPlayback), and list the field in the struct snippet and example for consistency. - Add an Unreleased "Added" changelog entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (3)
website/docs/reference/options.mdx (3)
983-989: ⚡ Quick winConsider documenting the
ApplicationNameForUserAgentfield in the table.The preferences table is missing a row for the
ApplicationNameForUserAgentfield. For documentation completeness, consider adding:
Name Description ApplicationNameForUserAgent A string value used as the application name portion of the user agent. When set to a non-empty value, overrides the default Wails suffix. Useful when sites reject the default identifier. This would appear between
FullscreenEnabledandEnableAutoplayWithoutUserActionto match the struct field order.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/docs/reference/options.mdx` around lines 983 - 989, Add a new table row documenting the ApplicationNameForUserAgent field: insert a row named ApplicationNameForUserAgent with the description "A string value used as the application name portion of the user agent. When set to a non-empty value, overrides the default Wails suffix. Useful when sites reject the default identifier." and place it between the existing FullscreenEnabled and EnableAutoplayWithoutUserAction rows so the table order matches the struct field order; ensure the formatting matches the other rows and includes the same link/format style as surrounding entries.
975-981: ⚡ Quick winConsider adding the missing
ApplicationNameForUserAgentfield to complete the struct documentation.The struct code block is missing the
ApplicationNameForUserAgent stringfield that exists in the actualmac.Preferencesstruct (betweenFullscreenEnabledandEnableAutoplayWithoutUserAction). Based on the actual implementation, the complete struct should be:type Preferences struct { TabFocusesLinks u.Bool TextInteractionEnabled u.Bool FullscreenEnabled u.Bool ApplicationNameForUserAgent string EnableAutoplayWithoutUserAction u.Bool }Including all fields ensures users have an accurate reference and can discover all available options.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/docs/reference/options.mdx` around lines 975 - 981, The Preferences struct documentation is missing the ApplicationNameForUserAgent field; update the code block for type Preferences to include the ApplicationNameForUserAgent string field between FullscreenEnabled and EnableAutoplayWithoutUserAction so the docs match the actual mac.Preferences implementation and users can discover that option.
995-998: ⚡ Quick winConsider including
ApplicationNameForUserAgentin the example for completeness.The example could demonstrate both boolean and string preference types:
Mac: &mac.Options{ Preferences: &mac.Preferences{ TabFocusesLinks: mac.Enabled, TextInteractionEnabled: mac.Disabled, FullscreenEnabled: mac.Enabled, ApplicationNameForUserAgent: "MyApp", EnableAutoplayWithoutUserAction: mac.Enabled, } }This would help users understand how to configure string-type preferences alongside the boolean ones.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/docs/reference/options.mdx` around lines 995 - 998, Add the string preference example to the Mac preferences block by including ApplicationNameForUserAgent in the mac.Preferences example; update the Preferences literal inside mac.Options to show ApplicationNameForUserAgent: "MyApp" alongside the existing boolean entries (TabFocusesLinks, TextInteractionEnabled, FullscreenEnabled, EnableAutoplayWithoutUserAction) so the doc demonstrates both string- and boolean-typed preference values.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@website/docs/reference/options.mdx`:
- Around line 983-989: Add a new table row documenting the
ApplicationNameForUserAgent field: insert a row named
ApplicationNameForUserAgent with the description "A string value used as the
application name portion of the user agent. When set to a non-empty value,
overrides the default Wails suffix. Useful when sites reject the default
identifier." and place it between the existing FullscreenEnabled and
EnableAutoplayWithoutUserAction rows so the table order matches the struct field
order; ensure the formatting matches the other rows and includes the same
link/format style as surrounding entries.
- Around line 975-981: The Preferences struct documentation is missing the
ApplicationNameForUserAgent field; update the code block for type Preferences to
include the ApplicationNameForUserAgent string field between FullscreenEnabled
and EnableAutoplayWithoutUserAction so the docs match the actual mac.Preferences
implementation and users can discover that option.
- Around line 995-998: Add the string preference example to the Mac preferences
block by including ApplicationNameForUserAgent in the mac.Preferences example;
update the Preferences literal inside mac.Options to show
ApplicationNameForUserAgent: "MyApp" alongside the existing boolean entries
(TabFocusesLinks, TextInteractionEnabled, FullscreenEnabled,
EnableAutoplayWithoutUserAction) so the doc demonstrates both string- and
boolean-typed preference values.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 9e92894e-2060-4925-aa27-e36e0d24fd00
📒 Files selected for processing (2)
website/docs/reference/options.mdxwebsite/src/pages/changelog.mdx
✅ Files skipped from review due to trivial changes (1)
- website/src/pages/changelog.mdx
Author
|
Thanks @leaanthony! Both items are done in 62b1e7c:
Sounds good on v3 being a separate follow-up. Ready for re-review whenever you get a chance. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
EnableAutoplayWithoutUserActiontomac.Preferences, mapping toWKWebViewConfiguration.mediaTypesRequiringUserActionForPlayback. Without it, there is no way to autoplay HTML5 video/audio in a Wails v2 macOS app — every<video autoplay>is blocked.Closes #5511.
Implementation
Mirrors the existing preference-passing pattern (compare
TabFocusesLinks,FullscreenEnabled):EnableAutoplayWithoutUserAction u.Booltomac.Preferences(v2/pkg/options/mac/preferences.go)bool *enableAutoplayWithoutUserActionto the Cstruct Preferences(WailsContext.h)IsSet()+bool2CboolPtr(...)(window.go)WKWebViewConfigurationwhen set:Defaults preserve WebKit's current behaviour (user gesture required) — opt-in only.
iOS in v3 already exposes the equivalent option (
EnableAutoplayWithoutUserActioninapplication_options.go), and the same gap is being filled for v3 macOS in a parallel PR.Note:
allowsInlineMediaPlaybackis iOS-only onWKWebViewConfiguration(verified by macos-latest compile failure with Xcode 16.4 SDK), so it is intentionally not exposed on macOS.Test plan
macos-latest/ Xcode 16.4)<video autoplay src="...">andMac.Preferences.EnableAutoplayWithoutUserAction: mac.Enabledautoplays without a clickSummary by CodeRabbit
New Features
Documentation