= Screenlight User Guide
:screenlight-page:

anchor:table_of_contents[]

{start-toc}

[[toc]]
[compact]
* link:#under-toc[Conventions]
* link:#_what_is_screenlight[What is Screenlight?]
* link:#_typical_use_cases[Typical Use Cases]
* link:#_overview[Overview]
* link:#_how_do_you_use_it[How Do You Use It?]
* link:#_summary_of_files[Summary of Files]

{nbsp}




[[under-toc]]
== Conventions
{top}
[icon="./images/icons/info.png"]
[NOTE]
This is additional information

[icon="./images/icons/tip2.png"]
[NOTE]
This is a tip

[icon="./images/icons/settings.png"]
[NOTE]
This is an example configuration or setting

<<table_of_contents,Table of Contents>>

{nbsp}




== What is Screenlight

It is a way of adjusting the screen brightness, contrast, and colour temperature for the current session and using your chosen settings in future sessions. 

<<table_of_contents,Table of Contents>>

{nbsp}




== Typical Use Cases

Your system suffers from any or all of the following:

* The screen is either too dark or too light and cannot be adjusted by the keyboard +
* The difference between light and dark areas is too little or too great +
* Using the screen at night gives you eye strain and/or insomnia +

<<table_of_contents,Table of Contents>>

{nbsp}




== Overview

For convenience, settings are presented as those suited to use during the day and those suited to use at night:

* Day - permits modifying either or both brightness and contrast, +
* Night - permits modifying either or both brightness and colour balance. +

Adjusting the brightness level lightens or darkens the entire screen. Every pixel on the screen is lightened or darkened by the same amount.

Adjusting the contrast level increases or reduces the difference in brightness between light and dark areas on the screen. Values at opposite ends of the scale maximize or minimize the separation between light and dark pixels.

Adjusting the colour temperature changes the balance of red and blue shown on the entire screen. Higher levels of red make the screen appear warmer, higher levels of blue make the screen appear cooler.

A cooler screen tone is thought to mimic daylight and inhibit sleep.  A warmer screen hue is thought to reduce that effect.

<<table_of_contents,Table of Contents>>

{nbsp}




== How Do You Use It?

Screenlight may be started in two ways:

* Manually by clicking on its icon +
* Automatically by an entry in the system startup file

{nbsp}

[icon="./images/icons/tip2.png"]
[TIP]
No changes will be made to the screen until configuration values have been set and saved.

<<table_of_contents,Table of Contents>>

{nbsp}


===  Apply Settings Manually

Click on its icon +
image:screenlight/screenlight.png[]Screenlight

{nbsp}

{nbsp}

A menu is displayed

image:screenlight/screenlight_menu1.jpg[]

{nbsp}

If you have previously saved your preferred values and want to apply them, choose the corresponding item.

{nbsp}

If you are about to create your preferred values for the first time, or want to alter them, choose the appropriate entry.

The configuration file opens in your preferred text editor.  Enter the values and save the file. 

When you save the file and it contains valid values, they are automatically and immediately applied. +
This is an easy way to find the ones that suit you best.

{nbsp}

[icon="./images/icons/info.png"]
[NOTE]
[red]*#Important:# [black]#When you have decided which values to keep, shut down the text editor completely.#*

<<table_of_contents,Table of Contents>>

{nbsp}


=== Apply Settings Automatically at Boot Up

Ensure the following entry is present in the session startup file.

[icon="./images/icons/settings.png"]
[NOTE]
==== 
Example entry to automatically apply day values
----
# Uncomment after assigning values for screen brightness, contrast and colour temperature
screenlight.sh day &
----
====
To apply night values replace the word *[black]#day#* with *[black]#night#* in the above entry.

{nbsp}

[icon="./images/icons/tip2.png"]
[TIP]
The session startup file is in a hidden folder in your home folder +
.desktop-session/startup +
 +
An easy way to open it is +
Control Centre&rarr;Session&rarr;User Desktop-Session

<<table_of_contents,Table of Contents>>

{nbsp}




== Summary of Files

*Configuration files:*

....
.config/screenlight/
├── screenlight-day.conf
└── screenlight-night.conf
....

{nbsp}

*Executable files:*
....
/usr/local/bin/
├── screenlight-menu.sh
└── screenlight.sh
....

{nbsp}

*Library files:*
....
/usr/local/lib/screenlight/
├── button-icons
│   ├── Cancel-16.png
│   ├── Check-16.png
│   ├── Close-16.png
│   └── Help-16.png
└── lib-screenlight
....

<<table_of_contents,Table of Contents>>

{nbsp}





////
== Getting Started
{top}

Screenlight may be started in three ways:

* Manually from the main menu in _Icon_ mode (Illustrated in scenario 1) +
* Manually from the main menu in _Run Once_ mode (Illustrated in scenario 2) +
* Automatically launch _Icon_ mode at startup




=== Automatically Launch Icon Mode at Startup

To automatically start icon mode, place an item in the session startup file.


[icon="./images/icons/info.png"]
[NOTE]
The session startup file is in a hidden folder in your home folder +
.desktop-session/startup


[icon="./images/icons/tip2.png"]
[TIP]
A simple way to add an item to run at session startup +
1. antiX Control Center->Session Tab->User Desktop Session +
2. When the editor opens->Startup Tab +
3. Type in your item +
4. Save the file and close the editor


[icon="./images/icons/settings.png"]
[NOTE]
==== 
Example entry to automatically place an icon in taskbar at startup
----
# Place an icon for streamlight in the taskbar tray
streamlight-gui-launcher.sh --icon &
----
====
 
{nbsp}

{nbsp}





== Play the Live Stream in Scenario 1
{top}

From the antiX menu select +
image:streamlight/dp_streamlight-gui-launcher.png[]Streamlight

{nbsp}

A window opens asking which mode is wanted.

image:streamlight/dp_launch_mode.jpg[]

Press the _Icon_ button to place an icon in the taskbar

{nbsp}

In this scenario the lightweight web browser, Dillo is used to browse Youtube videos.  This is for the sake of illustration only, other web browsers may also be used.

From the antiX menu select +
image:streamlight/p_start_dillo.png[]Dillo

{nbsp}

Clear the address area and copy and paste the following address, then press the enter key +
`https://www.youtube.com/results?search_query=runwiththedolphin+antix`

image:streamlight/p_dillo_address_bar.jpg[]

The address is provided here for your convenience and to simplify demonstrating the scenario. +
It displays a list of antiX help videos to save you the task of searching for them.

[icon="./images/icons/tip2.png"]
[TIP]
To copy, highlight the address with your cursor +
To Paste, click the middle button of your mouse or simutaneously press left and right buttons

Right click on a video image or link address +
In the cascading menu choose _Link Menu->Copy Link Location_

[icon="./images/icons/tip2.png"]
[TIP]
Alternatively, you can click on a link and follow it until the address of the video +
is shown in the address bar then highlight the address with the cursor.

Left click on the Streamlight icon in the taskbar to pass on the address

{nbsp}

A window opens showing all the resolutions (on screen video sizes) in which the video is available.

image:streamlight/p_video_resolution.jpg[]

Select one and press the _OK_ button.

[icon="./images/icons/tip2.png"]
[TIP]
_best_ and _worst_ are aliases for the highest and lowest available resolutions. +
They produce either the largest or smallest on screen video size. +
The smaller the size, the lower is the demand on your system when playing the video.

{nbsp}

A window opens asking whether to play or download the stream.

image:streamlight/dp_play_or_download.jpg[]

If a buton is not pressed, _Play_ is automatically started after a timeout

{nbsp}

{nbsp}





== Download the Stream in Scenario 2
{top}

Use the cursor to highlight the following video address +
`https://www.youtube.com/watch?v=IZxV6I1wjns`

The address is provided here for your convenience and to simplify demonstrating the scenario. +
It simulates obtaining it from an email or other application. The video it points to is quite brief and downloads as a small file.

{nbsp}

From the antiX menu select +
image:streamlight/dp_streamlight-gui-launcher.png[]Streamlight

{nbsp}

A window opens asking which mode is wanted.

image:streamlight/dp_launch_mode.jpg[]

Press the _Run Once_ button +
This will use the video address you have currently highlighted and quit when it has finished.

{nbsp}

A window opens showing all the resolutions (on screen video sizes) in which the video is available.

image:streamlight/d_video_resolution.jpg[]

Select _best_ and press the _OK_ button.

[icon="./images/icons/tip2.png"]
[TIP]
_best_ and _worst_ are aliases for the highest and lowest available resolutions. +
They produce either the largest or smallest on screen video size. +
The larger the size, the greater is the demand on your system when playing the video.

{nbsp}

A window opens asking whether to play or download the stream.

image:streamlight/dp_play_or_download.jpg[]

Press the _Download_ button.

[icon="./images/icons/tip2.png"]
[TIP]
If a button is not pressed before the timeout ends the stream defaults to _Play._

{nbsp}

A window stays open while the stream is downloading.

image:streamlight/d_stream_downloading.jpg[]

All downloads are saved as a file in your Downloads folder. 


[icon="./images/icons/tip2.png"]
[TIP]
The file is named in a standard way. +
The first word is watch followed by: +
the resolution you selected, +
the date +
the time +
.mp4 

{nbsp}

{nbsp}




== Summary of Files
{top}

Log File

* Log file is located in /home/USERNAME/.streamlight.log

Executable files are located in /usr/local/bin/

* streamlight-gui-launcher.sh is the launcher script
* streamlight.sh is the script that does all the work

Menu file is located in /usr/share/applications/antix/

* streamlight-gui-launcher.desktop 

Icon files are located in /usr/share/pixmaps/

* cross_red.png
* info_blue.png
* questionmark_yellow.png
* streamlight-gui-launcher.png

{nbsp}

{nbsp}





== References
{top}

streamlink +
https://streamlink.github.io/

mpv +
http://mpv.io/





== Video
{top}
antiX 15 - Streamlight - Stream Video on Low Powered Hardware by runwiththedolphin https://www.youtube.com/watch?v=2M5B5aXBDwk
////
