           !NetRadio (C) Bernard Veasey 2014-2024 version 0.53
                        >>> G I F T W A R E <<<
                     Email: bernard@bapfish.org.uk
                    Web: http://www.bapfish.org.uk/

DESCRIPTION
-----------
!NetRadio was made as a front-end for MPlayer to play Internet Radio.
NetRadio (using Mplayer) will also playback WAV, MP3, FLAC and M3U files.


INSTALLATION
------------
Just 'drag' !NetRadio to your 'drive' in your chosen location.

You must also make sure that you have !MPlayer and that it has been seen.
On some computers it might already be installed in !Boot.Resources
It comes from:
http://www.riscos.info/packages/arm/Audio/mplayer_svn-20120914-1.zip
http://www.riscos.info/packages/AudioDetails.html
The latest VFP MPlayer update version comes from:
http://www.riscosports.co.uk/vfp/mplayerlatest.zip (18 Sep 2020)

If you use Aemulor that limits your RISC OS computer to 28MB of memory,
so make sure you startup your computer without using Aemulor before using
Mplayer which usually needs more than that.


INSTRUCTIONS
------------
Page through the list of radio stations using the mouse or arrow keys and
click 'Play' or press RETURN to 'Play' the selected radio station.

To search for a radio station in the 'NetRadio' radio station list,
put the caret in the Search box by clicking in it or by pressing f4,
enter the search criteria and press RETURN (or click 'Search').
The first match will be displayed.  If nothing is found you will hear a
beep.  If more than one match is found you can use the 'right' arrow key
to do a 'next match' and the 'left' arrow key to do a 'last' match.
When you have found what you are searching for press RETURN or click PLAY.
Right clicking the 'Search' icon will blank the Search box.

If you are not connected to working Internet, Mplayer will not be able to
play any Internet radio stations!

f5 - RISC OS Volume down - Decreases RISC OS volume.
f6 - RISC OS Volume up - Increases RISC OS volume.

     NetRadio needs to have the input focus for the above keys to work.

9  - Mplayer Volume down (as provided by MPlayer) - Changes MPlayer volume
0  - Mplayer Volume up (as provided by MPlayer) - Changes MPlayer volume
q  - Quit playing (as provided by MPlayer)
     and Quit saving
m  - Mute/un-mute Mplayer.

     The MPlayer TaskWindow needs to have the input focus for the
     above keys to work.


ICONBAR ICON CONTROLS
---------------------
'Select'           Opens 'NetRadio' window.
'Adjust'           Closes 'NetRadio' window.
                   Regains input focus to enable opening of main window
                   using the NetRadio Hot Key which by default is f2.
'Menu'             Opens 'NetRadio' menu.


MAIN NETRADIO WINDOW CONTROLS
-----------------------------
** mouse **

 Station Name      Select a Radio Station
                   You can drag to reposition in the list.
                   You can drag to the top of the whole list by
                   dropping on the up arrow in the NetRadio window.
                   You can drag to the bottom of the whole list by
                   dropping on the down arrow in the NetRadio window.

 UP arrow          Proceed UP list.
 SHIFT/UP arrow    Proceed UP list by ten.
 CTRL/UP arrow     Proceed to beginning of list.

 DOWN arrow        Proceed DOWN list.
 SHIFT/DOWN arrow  Proceed DOWN list by ten.
 CTRL/DOWN arrow   Proceed to end of list.

 Play (select)     Play the selected radio station.
                   The sound will be faded in.
                   If you open the 'Options' window you will see the
                   volume level amount rising.

 STOP              STOP playing the current radio station.
 
 Mute              Mute/un-mute the RISC OS sound.
 
 Info (select)     Opens the NetRadio 'Radio Station Information' window.
 Info (adjust)     Closes the 'Radio Station Information' window.
 
 Save (select)     'Save Stream' or opens 'Save Stream' window.
 Save (adjust)     Close 'Save Stream' window.
 
 Search (select)   Initiate a search after having entered the search
                   criteria previously.
 Search (adjust)   Blank the contents of the search box.

 Menu item         Select the clicked menu item.

** keys **

 UP arrow          Proceed UP list.
 SHIFT UP arrow    Proceed UP list by ten.
 PageUP            Proceed UP list by ten.
 CTRL UP arrow     Proceed to beginning of list.

 DOWN arrow        Proceed DOWN list.
 SHIFT DOWN arrow  Proceed DOWN list by ten.
 PageDOWN          Proceed DOWN list by ten.
 CTRL DOWN arrow   Proceed to end of list.

 LEFT arrow        Proceed down 'found' list.
 RIGHT arrow       Proceed up 'found' list.

 RETURN            Play the selected Radio Station.
                   The sound will be faded in.
                   If the caret is in the 'Search' icon, a search is
                   implemented.

 CTRL f2           Close 'NetRadio' window and lose 'Input Focus'.

 DELETE            STOP playing the current radio station.

 f2  (Hot Key)     Open (or close) the main 'NetRadio' window.  This is the
                   NetRadio Hot Key which can be changed in the NetRadio
                   Options window.

 f3                Saves the current 'list' of radio stations.

 SHIFT f3          Opens the Save Stream save as window.

 f4                Search - Puts the caret in the 'Search' icon.
                   You can then press RETURN or click 'Search' to initiate
                   the search.

 f5                Decrease RISC OS system sound level.
 f6                Increase RISC OS system sound level.
                   The current level (1-127) is shown in the NetRadio
                   Options window and is saved with the NetRadio options.
                   When NetRadio starts up, this saved level is set as the
                   current RISC OS volume level.

 f7                Opens Radio Station Information window.

 Please note that 'NetRadio' needs to have the 'input focus' for the above
 keypresses (except the Hot Key - f2) to work.  When the main 'NetRadio'
 window is opened it has the 'input focus'.  If it loses the 'input focus'
 by another application grabbing it, clicking on the 'NetRadio' iconbar
 icon, the main 'NetRadio' window or pressing the NetRadio Hot Key gives
 'NetRadio' the 'input focus' again.  When 'NetRadio' has the 'input focus'
 its title bar is coloured yellow.


ICONBAR and NETRADIO WINDOW MENU
--------------------------------
Info            Opens the NetRadio 'About this program' window.
                Clicking the web 'globe' icon opens the NetRadio web page.
                Clicking the 'i' blue information icon inside this window
                opens the !NetRadio.!Help file.

Station Info    Opens the 'Radio Station Information' window.

Save Stream     Save the Radio Stream as a 16-bit, 24-bit or 32-bit WAV
                file.

                The default record time is set to 10 minutes (600 secs).
                (Other options are 60 minutes (3600 secs)).
                You can set this in the 'Save as' window.
                Max: 100 minutes - Min: 1 minute
                To cancel the recording before this time is up, press 'q'
                while Mplayer has the input focus.
                Mplayer currently doesn't save the RISC OS filetype with the
                saved file.  After Mplayer has finished saving the file,
                just drag it to the NetRadio icon bar to filetype it as a
                WAV file (&fb1) if you are going to be using the WAV file
                on RISC OS.
                Be aware that WAV files are quite large, the higher the bit
                rate the larger they are too.
                The saved 16-bit, 24-bit or 32-bit WAV files can all be
                played back using NetRadio/Mplayer or on a Windows PC.
                16-bit and 24-bit WAV files play back on DigitalCD.
                NetRadio cannot save a radio stream and play the radio at
                the same time.  If it could, you would probably require a
                more powerful computer anyway.
                ***************************************************
                **  The recordings made by this program are the  **
                ** responsibility of the user as to whether they **
                **  are allowed by the laws of the country you   **
                **   or the radio station reside in.  I am not   **
                **    responsible for any recordings you make    **
                **              using this program.              **
                ***************************************************

Options         Opens the 'Options' window.

Save            Saves the current 'list' of radio stations.

Quit            Quit this program.
                If the 'Iconbar icon' option is off and the 'NetRadio'
                window is closed, you can quit 'NetRadio' from the RISC OS
                Task Manager window.

** keys **

TAB             Cursor to next writable icon.

RETURN          Saves the current 'list' of radio stations.


RADIO STATION INFORMATION WINDOW
--------------------------------
This can be used to edit the existing radio station information or you
can add a new radio station if you know its address.

Name            The name of the radio station.
Logo            The name of the sprite for the radio station logo.
Volume          The MPlayer volume setting for the radio station.
                Different radio stations are at different volumes, so you
                may have to come back here and edit it later once you
                have heard its volume.
URL             The Internet address of the radio station.

Add             Add a new radio station.
Delete          Delete the current radio station.
Arrow keys      Move up or down the radio station list.
Sort (select)   Sort the radio station list into alphabetical order.
Sort (adjust)   Re-load the saved radio station list if you want to revert
                back to your previously saved order.  This only works if you
                haven't saved your newly sorted order yet of course.
Cancel          Cancel
Save            Save the radio station list.

If you create a sprite logo for a radio station, you need to create
a small and large version. They need to be 62x62 pixels and 130x130 pixels
and saved in the !NetRadio.Resources.Icons and !NetRadio.Resources.BigIcons
sprite files.

You can copy and paste text into these icons by using the 'IcnClipBrd'
module from http://www.stevefryatt.org.uk/software/clipboard/

Using NetSurf - Ctrl/C in NetSurf - Ctrl/V in NetRadio
Using Zap     - Ctrl/E in Zap     - Ctrl/V in NetRadio
etc


OPTIONS WINDOW
--------------
Big                If set, NetRadio loads the 'big' version of the
                   NetRadio templates and icons files.
                   This is for when the user is viewing it on a TV
                   screen and usually needs to ses a larger version
                   from a distance.
                   If you change this option and click SAVE, you will
                   need to restart the program to view the changes.

Open on startup    Sets the 'Open on startup' option on/off.
                   When set to 'on', the main 'NetRadio' window is opened
                   automatically when !NetRadio is first run.

Icon bar icon      Toggles display of the 'Net Radio' iconbar icon.

Auto save          If set the 'NetRadio' radio station list is automatically
                   saved after a radio station has been deleted.

Auto Play          If set, the set radio station is played when NetRadio
                   is first run.

Auto close         If set, the main 'NetRadio' window will automatically
                   close after a radio station has been 'Played'.

Verbose Mplayer    If set the Mplayer task window will produce textual
                   output.  You need this switched on to enable you to view
                   the current radio stream track name if the radio station
                   supports this feature.

Vertical wrap      If set, when paging through the 'NetRadio' object list
                   the first and last items will wrap around.

Stop Mplayer       If set, Mplayer will stop when NetRadio is Quit.

Hot Key            This is the NetRadio Hot Key code that opens and closes
                   the main NetRadio window.  Just press the key you
                   require and the key code will automatically be entered
                   in the icon.  By default it is 386 which is f2.
                   The left 'Windows' key (448) is another option.
                   NB. Function keys are probably best used including the
                   use of SHIFT, CTRL and CTRL/SHIFT with the desired key.

Start station      This is the number of the radio station that plays
                   if the 'Auto Play' option (above) is set.
                   The radio station is also highlighted at program startup.

Volume             This shows the RISC OS sound level set using the F5 and
                   F6 keys.

SAVE               Saves the current 'NetRadio' options, the NetRadio Hot
                   Key code and the position of the 'NetRadio' window.


PLAYING BACK AUDIO FILES
------------------------
NetRadio (using Mplayer) can playback the 16-bit, 24-bit or 32-bit radio
stream WAV file(s) you have recorded.
So long as NetRadio has been seen, just double-click a WAV file and it will
be played.  NetRadio will automatically be run if it hasn't been loaded.
You can also drag a WAV file to the main NetRadio window or the NetRadio
icon bar icon and it will be played.

NetRadio (using Mplayer) will also playback MP3 and FLAC audio files.
Mplayer takes a long time to start a FLAC audio file.  It hasn't crashed.
It just takes a long time to start!

If, when an audio file is double-clicked, you don't want it to load
!NetRadio, put a '|' before the relevant lines in '!NetRadio.!Boot' and
'!NetRadio.!Run'.  This could be because you prefer !DigitalCD to play
your MP3 files.


ZAP TASK WINDOW
---------------
There is a setting in ZAP 1.48+ that when set lets the Zap Task window
automatically close when NetRadio stops Mplayer playing the radio
or 'q' is pressed when Mplayer has the input focus.
To set this setting from the Zap icon bar icon:  Tick the option:
Menu > Options > Mode > Taskwindow > Auto-close
then
Menu > Options > Save options


StrongED TASK WINDOW
--------------------
There is a setting in StrongED 4.70 that when set lets the StrongED Task
window automatically close when NetRadio stops Mplayer playing the radio
or 'q' is pressed when Mplayer has the input focus.
To set this setting from the StrongED icon bar icon:  Tick the option:
Choices > Misc > 'Kill taskwindow when child task quits'.
then click 'Save' to save the StrongED options.


GENERAL INFORMATION
-------------------
When a change has been made to the 'list', a star is placed to the right
of the !NetRadio window title showing that it needs to be saved.

The SPRITE relating to the currently selected radio station in the
'NetRadio' list is shown in the top left of the main 'NetRadio' window.
The default sprite is called 'radio'.  The user can add sprites to the
'!NetRadio.Resources.Icons' sprite file if required.
They should be 62x62 pixels.
If you do, you should also add a sprite to the '!NetRadio.Resources.BigIcons'
sprite file.  These should be 130x130 pixels.

The number displayed in the main 'NetRadio' window is the position within
the 'NetRadio' object list.

Slower RISC OS computers cannot save a 320K radio stream properly as
they are not powerful enough.  It has been confirmed that 320K radio
streaming can be saved on an ARMiniX (PandaboardES) computer with
RISC OS 5.21.

============================================================================

The AppName '!NetRadio' has been allocated to me by RISC OS Open
on 30 Sep 2014.

============================================================================
ABOUT GIFTWARE
--------------
This program is giftware, not public domain.  Giftware means that if you
use this program regularly you are asked to send the author a 'gift'.

By sending a gift, your support helps to provide updates to this program
and an incentive for other RISC OS software to be developed.

To make a gift
--------------
Please send your chosen amount (5ukp suggested)
Online donations can be made at http://www.bapfish.org.uk/software.htm

Upgrades
--------
The current site to obtain the latest version is from:

    http://www.bapfish.org.uk/

or use !Store

End-User licence conditions
---------------------------
You may give a copy of this software to a friend but you may only
distribute this software from your website or on a CD-ROM or similar
device in bulk with the express permission of the author.
In the event of my death, this software will become open-sourced.

Disclaimer of liability
-----------------------
1. The software is supplied 'as is' the Author makes no warranty, whether
   express or implied, as to the merchantability of this software or its
   fitness for any particular purpose.

2. In no circumstances will the Author be liable for any damage, loss of
   profits, goodwill or for any indirect or consequential loss arising out of
   your use of the Software, or inability to use the Software, even if the
   Author has been advised of the possibility of such loss.

3. The author reserves the right to change the specification of this program
   without notice.


Bug Reports and Suggestions
---------------------------
Bug reports and suggestions will be welcome from all users, even if you have
not made a gift (yet).  It has been tested on an ARMX6 (RISC OS 5.25),
a Raspberry Pi (RISC OS 5.24).

Please enclose the following information:

    Computer:

    RISC OS version:

    Software version: 

    Problem/Suggestion:

    Any other relevant information:

and contact me by Email at:

    bernard@bapfish.org.uk
    ~~~~~~~~~~~~~~~~~~~~~~

Other Software by Bernard can be found at:

    http://www.bapfish.org.uk/
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
