Oxygen - Working and relaxing app

Version 1.0.0

Introduction

Support: SakuraLeaf

This documentation is to help you regarding install, set up & customization of the plugin. Please go through the documentation carefully to understand how this plugin works.

Requirements

In order to work properly the plugin needs the following:

  1. WordPress 6.8+. Oxygen it's built on top of WordPress as a plugin.

Installation

In order to use the plugin:

  1. Deactivate the free version (if it's installed and activated)
  2. Log in to your WordPress Admin Panel, go to Plugins > Add new > Upload. Upload the zip file
  3. Once you have uploaded the plugin, it automatically installs to your WordPress instance. Click the Activate button to activate it.

Main settings

Once you have installed the plugin, head to settings (Admin > OxygenApp settings). Here you can set up the General settings, set up Paddle subscriptions, edit the locales, and add/remove languages.

Google Auth

To set up Google Login, go to Admin > OxygenApp settings > General > Google Sign-In and activate "Activate Google Sign-In".

Steps to get the client id and the client secret

Paddle integration

Oxygen integrates with Paddle to handle subscription payments for Pro plans. Follow these steps to configure Paddle:

Paddle.com is a full-service billing platform aimed mainly at software companies, especially those selling digital products or subscriptions globally.

Some of the benefits are: Global scale with less complexity: Ability to sell in many countries, use local currencies/payment methods, handle VAT/sales tax and regulatory compliance in many jurisdictions without the company having to build all that from scratch.

Paddle supports sellers in over 200 countries and territories, allowing you to sell globally with no additional country-specific setup. Supported countries

Note! When testing with the sandbox, you can use Paddle's test card numbers (Example: 4242 4242 4242 4242). Use any CCV number and an expiration date in the future.

Prerequisites

Configuration Steps

  1. Navigate to Subscription Settings: Go to Admin > OxygenApp settings > Subscription gateways
  2. Enable Paddle: Check "Activate Paddle as gateway"
  3. API Credentials:
    • API Key: Get from Paddle Dashboard > Developer Tools > Authentication
    • Client-side token: Get from Paddle Dashboard > Developer Tools > Client-side tokens
  4. Product Configuration:
    • Monthly price ID: The Paddle price ID for your monthly subscription
    • Yearly price ID: The Paddle price ID for your yearly subscription
  5. Webhook Setup:
    • Copy the webhook URL from OxygenApp settings
    • In Paddle Dashboard, go to Developer Tools > Notifications
    • Add a new webhook destination with your URL
    • Copy the generated webhook secret key
    • Paste it into "Webhook secret key" field in OxygenApp settings
  6. Testing: Enable "Activate sandbox mode" to test with Paddle sandbox environment
  7. Notifications: Enter email address(es) to receive notification emails about subscription events

Webhook Events

The plugin automatically handles these Paddle webhook events:

Locales

Oxygen supports multiple languages and provides a flexible localization system for the frontend interface.

Managing Languages

  1. Go to Admin > OxygenApp settings > Languages
  2. Click "Add language" to add a new language
  3. Configure each language with:
    • RTL support: Enable for right-to-left languages like Arabic or Hebrew
  4. Set one language as the default using the radio button
  5. Delete languages using the delete button

Customizing Labels

All frontend text can be customized for each language:

  1. In the Languages tab, expand any language section
  2. Edit the text for each label (e.g., "Sign up", "Login", "My playlists")
  3. Changes are saved automatically
  4. Labels cover all UI elements:
    • Authentication forms (login, signup, password reset)
    • Navigation menus
    • Settings pages
    • Playlist management
    • Error and success messages
    • Subscription information

User Language Selection

Users can switch languages from the settings menu in the app. The selected language is saved to their profile and persists across sessions.

Sounds

Background sounds are ambient audio files that users can play, mix, and combine to create their ideal focus or relaxation environment.

Creating a Sound

  1. Go to Admin > Background Sounds > Add New
  2. Enter a title for the sound (e.g., "Rain", "Ocean Waves", "Coffee Shop")
  3. Configure the sound settings in the meta boxes:
    • Audio File: Upload an MP3 or OGG audio file (recommended: loopable tracks)
    • Icon: Upload an icon image to represent this sound (SVG or PNG recommended)
    • Default Volume: Set initial volume level (0-100, default 50)
    • Premium Sound: Check if this sound requires a Pro subscription
    • Requires Login: Check if users must be logged in to use this sound
    • Multi-language Labels: Enter translated names for each active language
  4. Assign the sound to one or more Admin Playlists (sound collections)
  5. Click "Publish" to make the sound available

Admin Playlists (Sound Collections)

Admin Playlists are curated collections of sounds that appear together in the frontend interface:

  1. Go to Admin > Background Sounds > Admin Playlists
  2. Create a new taxonomy term (e.g., "Nature", "Urban", "Meditation")
  3. Assign sounds to these collections when creating/editing sounds
  4. Collections help organize sounds and make them easier for users to discover

Sound Mixing

Users can play multiple sounds simultaneously and adjust individual volumes to create custom soundscapes. Each sound plays in a loop automatically.

Tips for Sound Content

Tip! To obtain the best performance and speed, use AWS S3 storage for sounds. There are free solutions out there as plugins: Example: amazon-s3-and-cloudfront/

Backgrounds

Backgrounds are the visual environments that users see while using the app. They can be static images or looping videos.

Creating a Background

  1. Go to Admin > Backgrounds > Add New
  2. Enter a title for the background
  3. Configure the background settings:
    • Background Type: Select "Image" or "Video"
    • Background File:
      • For images: Upload high-resolution JPG or PNG (1920x1080 or larger)
      • For videos: Upload MP4 or WebM file (recommend compressed, loopable videos)
    • Preview Icon: For videos, upload a thumbnail image shown before video loads
    • Premium Background: Check if this requires a Pro subscription
    • Requires Login: Check if users must be logged in to use this background
    • Category: Assign to one or more categories
    • Credits: Attribution for the background creator/source
      • Credits label: Name or description (e.g., "Photo by John Doe")
      • Credits URL: Link to creator's profile or source
  4. Click "Publish" to make the background available

Background Categories

Organize backgrounds into categories for easier browsing:

  1. Go to Admin > Backgrounds > Categories
  2. Create categories (e.g., "Nature", "Space", "Abstract", "Cityscapes")
  3. Assign backgrounds to categories when creating/editing them
  4. Users can filter backgrounds by category in the frontend

Background Credits

Credits are displayed at the bottom of the screen (if enabled in settings) to give proper attribution to content creators. This is especially important for stock photos/videos from services like Unsplash, Pexels, or Pixabay.

Best Practices

Tip! To obtain the best performance and speed, use AWS S3 storage for backgrounds. There are free solutions out there as plugins: Example: amazon-s3-and-cloudfront/

Extend the main functionality

Note! Oxygen-app-extended (GitHub), the plugin was created to help you extend the main plugin (oxygen-app) functionality without the need to edit any files within the main plugin. This way, updates to the main plugin will not affect custom functionality

Within the "oxygen-app-extended" plugin, you can find hooks examples on how you can override some of the oxygen-app plugin functionality. Example: Override logo, top menu, signup email message and such.

SMTP

Implementing SMTP (Simple Mail Transfer Protocol) in WordPress is one of the most effective ways to ensure your site’s emails (like contact forms, password resets, order confirmations, etc.) are delivered reliably.

Here are some solid WordPress plugins that implement SMTP (including via services like AWS SES) — all available on WordPress.org:

Users dashboard

Oxygen includes a user management dashboard accessible to administrators. This dashboard allows admins to view and manage registered users, their subscription status, and other relevant information.

Cloudflare Turnstile

Oxygen supports Cloudflare Turnstile as an alternative to reCAPTCHA for bot protection during user registration.

Setting up Cloudflare Turnstile

  1. Create a Cloudflare account and navigate to the Application security > Turnstile section.
  2. Register your site to obtain the Site Key and Secret Key.
  3. In OxygenApp settings, go to the Security tab and select Cloudflare Turnstile as the CAPTCHA provider.
  4. Enter the Site Key and Secret Key obtained from Cloudflare.
  5. Save the settings to enable Turnstile on your registration form.

Backgrounds/Sounds/categories re-order

  1. In order to easily re-oreder, we recommend the following plugins: Post Types Order, Custom Taxonomy Order
  2. In order to re-order the backgrounds/sounds/categories, go to the respective admin listing (Backgrounds/Sounds/Categories)
  3. Use the drag-and-drop handle on the left side of each item to drag it to the desired position.
  4. The new order will be saved automatically and reflected in the frontend interface.

Upgrade to OxygenApp Pro

Note! Before installing the pro version, it's recommended to deactivate the free version.

Resources

Here are some resources from which you can get sounds and backgrounds:

Tip! Make sure the sounds and video backgrounds have a perfect loop.

Tip! To obtain the best performance and speed, use AWS S3 storage. There are free solutions out there as plugins: Example: amazon-s3-and-cloudfront/

Development

Should you choose to extend the current functionality, to transpile the JS and Scss we've used Prepos (Prepros compiles your files, transpiles your JavaScript, reloads your browsers and makes it really easy to develop):

  1. The front-end web app is located at "oxygen-app/app/Views/Frontend". Open Prepos > Add project > oxygen-app/app/Views/Frontend. That's it, now any change will be compiled automatically.
  2. The JS and CSS used within the WP admin are located at oxygen-app/assets/admin/settings. Open Prepos > Add project > oxygen-app/assets/admin/settings. That's it, now any change will be compiled.

Changelog

Version 1.0.0 - Friday November 7, 2025