=== TuneSera Internet Radio Directory ===
Contributors: kkrabeyabosri
Tags: radio, radio player, radio directory, streaming, stations
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Build a searchable radio station directory with live playback, country browsing, CSV imports, and customizable layouts.

== Description ==

TuneSera Internet Radio Directory helps you publish and manage a radio station directory on your WordPress website. Visitors can browse stations, filter the directory, and listen to available radio streams.

Use the setup wizard to choose your directory page, configure its appearance, and add your first stations. Display the directory with the `[tunesera_directory]` shortcode.

= Free features =

* Manage radio stations, stream URLs, station logos, countries, cities, and genres.
* Display a responsive directory with list and grid layouts.
* Help visitors find stations with search, country browsing, and directory filters.
* Play supported radio streams with the built-in player.
* Show current track information when it is available from a supported stream provider.
* Import stations from the countries available in the bundled Free directory.
* Upload station data using the standard sample CSV column names.
* Review selected countries and station counts before importing.
* Preserve existing station records by default, or choose to update them during re-import.
* Follow import progress, inspect country results, and view or download import reports.
* Search and filter import history and export history as CSV.
* Configure the directory page, sorting, stations per page, accent color, and display options.

= Getting started =

1. Activate TuneSera Internet Radio Directory and open TuneSera > Setup Wizard.
2. Select a directory page and configure its URL and display defaults.
3. Add stations from the included directory or upload a CSV using the sample format.
4. Review your import options and start the import.
5. Customize the directory appearance and finish setup.

You can also place `[tunesera_directory]` on an existing page. Manage station records under TuneSera > Stations and import jobs under TuneSera > Import Stations.

= Free and Pro editions =

This download is the Free edition. Features marked Pro, including additional directory countries, custom CSV field mapping, and downloading imported station logos into the Media Library, require the separate Pro edition. Those premium implementations are not included in the Free package.

The import country list includes locked Pro countries with PRO badges. Settings includes disabled Pro previews for player, metadata, layout, and design options. These previews cannot be selected, saved, or activated in Free; the separate Pro edition supplies the premium functionality.

Free imports use the original station logo URLs. The Free edition does not require a Pro license for its included features.

= Stream availability =

TuneSera Internet Radio Directory is a directory and player, not an audio hosting service. Playback depends on the station's stream being online, its format being supported by the visitor's browser, and the provider allowing access. HTTPS websites may block insecure HTTP streams. Now-playing information is only displayed when the source provides usable metadata.

== Installation ==

1. In WordPress, go to Plugins > Add New Plugin > Upload Plugin.
2. Select the TuneSera Internet Radio Directory Free ZIP file and click Install Now.
3. Activate TuneSera Internet Radio Directory.
4. Open TuneSera > Setup Wizard and follow the setup steps.
5. Visit your selected directory page, or add `[tunesera_directory]` to a page of your choice.

For manual installation, extract the ZIP and upload the `tunesera-internet-radio-directory` folder to `/wp-content/plugins/`, then activate it in WordPress.

The release includes compiled assets. Node.js, npm, and a build step are not required to install or use the plugin.

== Frequently Asked Questions ==

= How do I display the radio directory? =

Choose a directory page in the setup wizard or add `[tunesera_directory]` to a WordPress page. You can adjust its appearance in TuneSera > Settings.

= Can visitors listen to stations? =

Yes. The built-in player plays supported station stream URLs. Stream availability and browser compatibility are controlled by the stream provider and visitor's browser.

= Can I import my own CSV file? =

Yes. Download the sample CSV from the import screen and use its standard column names. Custom field mapping is a Pro feature.

= What happens when I import a country again? =

Existing stations are preserved by default. During review, you can choose to update matching stations from the source. Records are matched using their source station IDs to avoid creating duplicates.

= Does importing continue if I close the page? =

Imports use background processing. Progress also depends on your site's scheduled tasks and loopback requests. Keeping the import page open can help processing continue on local sites or hosts with restricted background requests. You can return to Import History to inspect or manage a job.

= Are station logos downloaded to my Media Library? =

Not in the Free edition. Free imports keep the original logo URLs. Downloading imported logos into the Media Library is a Pro feature.

= Does deleting the plugin remove my station data? =

Data is retained by default. If you enable the uninstall cleanup option in the advanced settings before deleting the plugin, TuneSera Internet Radio Directory removes its station data and settings. Deactivating the plugin does not perform that cleanup.

== External services and privacy ==

The following disclosures apply to the Free edition. Remote requests depend on the station URLs you publish and the features you enable. TuneSera Internet Radio Directory does not require an external account to use its Free features.

= Bundled directory and same-site requests =

The included station directory, location catalog, flag icons, JavaScript and styles are bundled with the plugin. Importing the bundled directory does not call a third-party directory API. CSV uploads, directory searches, settings, reports and browser-assisted imports use your own WordPress site. Background imports make loopback requests to your site's admin-ajax.php endpoint; these are not requests to an external service.

= Station streams and images =

When a visitor plays a station, or enables session playback restoration, their browser connects to that station's stream host to receive audio. Displaying externally hosted logos or other station images also connects the browser to the image host. These image requests can occur when a directory, station page, player, admin image preview or live appearance preview displays an image, even without playing a station. Providers receive the requested URL, the visitor's or administrator's IP address and browser headers; a referrer may be sent depending on browser policy.

The destinations depend on the stream and image URLs stored in each station record, including records you import or add yourself. Each station's stream host operates its own service; there is no single stream provider or universal privacy policy. Review the stream and logo URLs in the station editor or CSV and consult the applicable station/hosting provider's terms and privacy policy before publishing. Removing or replacing an external image URL prevents requests to that image host; disabling metadata does not disable audio or image requests.

= Online Radio Box: station logos =

The bundled station records reference logos at https://cdn.onlineradiobox.com/. Browsers request these images to display station artwork in the directory, station pages, player and previews. The CDN receives the image URL, requester IP address and browser headers, including a referrer if permitted. Free imports retain these URLs rather than downloading images to the Media Library. TuneSera Internet Radio Directory does not call an Online Radio Box API to import stations or retrieve song metadata.

* Terms: https://onlineradiobox.com/terms
* Privacy policy: https://onlineradiobox.com/privacy?lang=en

= CSV source storage =

Uploaded CSV source files are stored privately in temporary database/cache storage for up to 30 days, rather than in the public Media Library. They may expire sooner if the site cache is cleared; upload the file again if needed. Import jobs retain their own station records for processing and reports. Legacy registered CSV uploads are migrated out of public uploads when an administrator next opens WordPress admin.

= Now-playing metadata =

Now-playing metadata is off by default and requires an administrator to enable it in Metadata settings. When enabled and requested, your WordPress server may contact the station's stream or metadata endpoint to retrieve the current track. Requests include the stream path or station identifier, and a User-Agent containing the TuneSera Internet Radio Directory version and your site's home URL. The host also sees your server's IP address and HTTP request headers. These requests originate from your server, rather than forwarding the listener's IP address. Existing installations must also explicitly enable this feature. It can be disabled again at any time.

For Icecast and SHOUTcast stations, requests use endpoints on the configured stream host, including status-json.xsl, stats, statistics, currentsong or 7.html. As a fallback, TuneSera Internet Radio Directory can read ICY metadata from the stream itself. The operator of that stream host provides the applicable terms and privacy policy. Metadata may be cached and refreshed while directory or player features request it; enabling metadata can cause requests without starting audio playback. Artwork URLs returned by a metadata provider may also be requested by the browser when displayed.

= Zeno: now-playing metadata and audio =

For supported Zeno-hosted streams, TuneSera Internet Radio Directory requests metadata from `https://api.zeno.fm/mounts/metadata/subscribe/` using the station's mount identifier. This request runs only when now-playing metadata is enabled and requested. Zeno receives the mount identifier, server IP address, plugin version and site home URL described above. Playback of a station hosted at stream.zeno.fm separately connects the visitor's browser to Zeno for audio, even when metadata is disabled. Neither request creates a Zeno account.

* Zeno terms: https://zeno.fm/terms/
* Zeno privacy policy: https://zeno.fm/privacy-policy/

= Optional sharing: WhatsApp, Facebook and X =

Sharing links contact the selected service only when a visitor activates them; TuneSera Internet Radio Directory does not load these services' sharing SDKs in the background. Sharing can be configured under TuneSera > Settings > Sharing. The destination receives the shared station page URL, any title described below, and normal browser request information such as IP address and browser headers. Existing cookies or a signed-in account may be handled by that service under its own policy. The visitor completes any post or message on the destination service.

* WhatsApp: https://wa.me/ opens sharing with the station title and page URL. A station's WhatsApp contact link instead passes that station's configured phone number to open a conversation. Terms: https://www.whatsapp.com/legal/terms-of-service ; Privacy: https://www.whatsapp.com/legal/privacy-policy
* Facebook: https://www.facebook.com/sharer/sharer.php receives the station page URL to prepare a share. Terms: https://www.facebook.com/legal/terms ; Privacy: https://www.facebook.com/privacy/policy/
* X: https://twitter.com/intent/tweet receives the station title and page URL to prepare a post on X. Terms: https://x.com/en/tos ; Privacy: https://x.com/en/privacy

Copy link writes the station URL to the visitor's clipboard without contacting a sharing service. Email opens the visitor's mail application with the station title and URL. Native sharing opens the browser/device share sheet and passes the title and URL to the destination chosen by the visitor; its provider's policies apply.

= Station website, contact and social links =

Station records can include website, Wikipedia and social-profile links. Clicking a link opens the configured third-party destination, which receives normal browser request information. These are outbound links, not background API integrations or embedded social widgets. The applicable terms and privacy policy are those published by the destination website. Email and telephone links open the visitor's configured application.

= Local browser storage =

The frontend uses browser local storage for directory preferences, playback state, and cached now-playing information. Site owners should account for these features and any external station providers in their site's privacy information.

== Changelog ==

= 0.1.0 =
* Initial Free release with a radio station directory, station management, and stream playback.
* Added a setup wizard for directory pages, URLs, imports, and appearance.
* Added directory and standard-format CSV imports with review, progress, and re-import options.
* Added country selection summaries, import reports, and searchable import history with CSV export.
* Added background import processing with a browser-assisted fallback.
* Included readable Free source code alongside the compiled runtime assets.

* Uses the TuneSera short name in the WordPress admin menu.
* Migrates existing station data and settings from previous plugin names.
* Supports the renamed TuneSera Pro add-on through shared extension hooks.

== Upgrade Notice ==

= 0.1.0 =
Initial Free release of TuneSera Internet Radio Directory.

== Credits ==

Country flag assets are provided by flag-icons under the MIT license. The license is included in `assets/vendor/flags/LICENSE`.

== Source code ==

Readable JavaScript/JSX and SCSS are included in assets/src/. The admin, frontend, station-editor and metabox directories contain the four entrypoints. Shared modules are included alongside them. assets/js/ and assets/css/ contain readable files served directly. Server-side source is in includes/, templates/ and the root PHP files.

The build/ directory contains the compiled JavaScript, CSS and WordPress dependency metadata needed to run the plugin. Installation does not require Node.js or compilation. Development manifests, build configuration, scripts, and tests are not included in the release ZIP. Legacy tune_planet_* and globetune_* shortcode aliases remain supported.

Third-party license notices are retained with the distributed assets.
