restream/README.md

# reStream

reMarkable screen sharing over SSH.

![A demo of reStream](extra/demo.gif)

## Installation

1. Clone this repository: `git clone https://github.com/rien/reStream`.
2. (Optional but recommended) [Install lz4 on your host and reMarkable](#sub-second-latency).
3. [Set up an SSH key and add it to the ssh-agent](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), then add your key to the reMarkable with `ssh-copy-id root@10.11.99.1`.

## Usage

1. Connect your reMarkable with the USB cable.
2. Make sure you can [open an SSH connection](https://remarkablewiki.com/tech/ssh).
3. Run `./reStream.sh`
4. A screen will pop-up on your local machine, with a live view of your reMarkable!

### Options

- `-h --help`: show usage information
- `-p --portrait`: shows the reMarkable screen in portrait mode (default: landscape mode, 90 degrees rotated tot the right)
- `-s --source`: the ssh destination of the reMarkable (default: `root@10.11.99.1`)
- `-o --output`: path of the output where the video should be recorded, as understood by `ffmpeg`; if this is `-`, the video is displayed in a new window and not recorded anywhere (default: `-`)
- `-f --format`: when recording to an output, this option is used to force the encoding format; if this is `-`, `ffmpeg`’s auto format detection based on the file extension is used (default: `-`).
- `-w --webcam`: record to a video4linux2 web cam device. By default the first found web cam is taken, this can be overwritten with `-o`. The video is scaled to 1280x720 to ensure compatibility with MS Teams, Skype for business and other programs which need this specific format.

If you have problems, don't hesitate to [open an issue](https://github.com/rien/reStream/issues/new) or [send me an email](mailto:rien.maertens@posteo.be).

## Requirements

On your **host** machine:
- Any POSIX-shell (e.g. bash)
- ffmpeg (with ffplay)
- ssh

On your **reMarkable** nothing is needed, unless you want...

### Sub-second latency

To achieve sub-second latency, you'll need [lz4](https://github.com/lz4/lz4)
on your host and on your reMarkable.

You can install `lz4` on your host with your usual package manager. On Ubuntu,
`apt install liblz4-tool` will do the trick.

On your **reMarkable** you'll need a binary of `lz4` build for the arm platform,
you can do this yourself by [installing the reMarkable toolchain](https://remarkablewiki.com/devel/qt_creator#toolchain)
and compiling `lz4` from source with the toolchain enabled, or you can use the
statically linked binary I have already built and put in this repo.

Copy the `lz4` program to your reMarkable with
`scp lz4.arm.static root@10.11.99.1:/home/root/lz4`, make it executable with
`ssh root@10.11.99.1 'chmod +x /home/root/lz4'` and you're ready to go.

## Troubleshooting

Steps you can try if the script isn't working:
- [Set up an SSH key](#installation)
- Update `ffmpeg` to version 4.
-												Add README

											
										
										
											2020-02-12 13:19:06 +01:00
+								# reStream
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
+								reMarkable screen sharing over SSH.
-												Add demo

											
										
										
											2020-03-12 00:29:18 +01:00
+								![A demo of reStream](extra/demo.gif)
-												Update README

- add installation instructions
- remove mention of script copying zstd

											
										
										
											2020-03-12 08:43:17 +01:00
+								## Installation
-												Clarify SSH key setup

											
										
										
											2020-03-30 21:33:44 +02:00
+. Clone this repository: `git clone https://github.com/rien/reStream`.
 . (Optional but recommended) [Install lz4 on your host and reMarkable](#sub-second-latency).
 . [Set up an SSH key and add it to the ssh-agent](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), then add your key to the reMarkable with `ssh-copy-id root@10.11.99.1`.
-												Update README

- add installation instructions
- remove mention of script copying zstd

											
										
										
											2020-03-12 08:43:17 +01:00
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
+								## Usage
 . Connect your reMarkable with the USB cable.
 . Make sure you can [open an SSH connection](https://remarkablewiki.com/tech/ssh).
-												Add parameters to README, ssh timeout to 1s

Changed the README to reflect the command line options added with
bcf62e3. Also incorporates the SSH timeout of 1 second added by the
initial PR (#10).

Co-authored-by: Aaron David Schneider <aaron.david.schneider@gmail.com>

											
										
										
											2020-04-02 14:14:36 +02:00
+. Run `./reStream.sh`
-												Update README

- add installation instructions
- remove mention of script copying zstd

											
										
										
											2020-03-12 08:43:17 +01:00
+. A screen will pop-up on your local machine, with a live view of your reMarkable!
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
-												Add parameters to README, ssh timeout to 1s

Changed the README to reflect the command line options added with
bcf62e3. Also incorporates the SSH timeout of 1 second added by the
initial PR (#10).

Co-authored-by: Aaron David Schneider <aaron.david.schneider@gmail.com>

											
										
										
											2020-04-02 14:14:36 +02:00
+								### Options
-												Add examples to usage info

											
										
										
											2020-04-07 11:48:46 +02:00
+								- `-h --help`: show usage information
 								- `-p --portrait`: shows the reMarkable screen in portrait mode (default: landscape mode, 90 degrees rotated tot the right)
-												Allow choosing the video output

Instead of simply playing back the frames through `ffplay`, I thought it
might be interesting to be able to record the sequence to a video file
or to use it as part of a stream.

I have in mind the use case of making educational videos/live streams
where the tablet can be used as a kind of remote blackboard by teachers,
which is especially relevant currently. But there are certainly other
use cases!

Changes
=======

This commit adds two new options to that effect:

* `-o --output`: Path of the output as understood by `ffmpeg` (usually a
file name). If this is `-` (as it is by default), the existing behavior
of playing the stream through `ffplay` is restored.

* `-f --format`: When recording to an output, this option can be used to
force the encoding format. If this is `-` (again, the default),
`ffmpeg`’s auto format detection is used (based on the file extension).

Because of the possible confusion between the newly added `--output`
option and the existing `--destination` option for specifying the source
address, I suggest renaming the `--destination` option to `--source`
(this is implemented in this commit).

Examples
========

Record to a file
----------------

```sh
./reStream.sh -o remarkable.mp4
```

Caveat: The recorded file plays back too fast.
I am not sure how to fix this.

Create an UDP MPEG-TS stream
----------------------------

```sh
./reStream.sh -o "udp://127.0.0.1:1234" -f "mpegts"
```

This sends frames over UDP to the specified port using the MPEG-TS
format (see <https://trac.ffmpeg.org/wiki/StreamingGuide>). This stream
can then be connected, for example, to OBS for live streaming (see
<https://connect.ed-diamond.com/Linux-Pratique/LP-096/Enrichir-sa-diffusion-de-contenus-multimedias-avec-OBS>
in French).

											
										
										
											2020-04-02 19:32:59 +02:00
+								- `-s --source`: the ssh destination of the reMarkable (default: `root@10.11.99.1`)
 								- `-o --output`: path of the output where the video should be recorded, as understood by `ffmpeg`; if this is `-`, the video is displayed in a new window and not recorded anywhere (default: `-`)
 								- `-f --format`: when recording to an output, this option is used to force the encoding format; if this is `-`, `ffmpeg`’s auto format detection based on the file extension is used (default: `-`).
-												Add video4linux2 support

											
										
										
											2020-04-14 10:46:07 +02:00
+								- `-w --webcam`: record to a video4linux2 web cam device. By default the first found web cam is taken, this can be overwritten with `-o`. The video is scaled to 1280x720 to ensure compatibility with MS Teams, Skype for business and other programs which need this specific format.
-												Add parameters to README, ssh timeout to 1s

Changed the README to reflect the command line options added with
bcf62e3. Also incorporates the SSH timeout of 1 second added by the
initial PR (#10).

Co-authored-by: Aaron David Schneider <aaron.david.schneider@gmail.com>

											
										
										
											2020-04-02 14:14:36 +02:00
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
+								If you have problems, don't hesitate to [open an issue](https://github.com/rien/reStream/issues/new) or [send me an email](mailto:rien.maertens@posteo.be).
-												Add README

											
										
										
											2020-02-12 13:19:06 +01:00
 								## Requirements
 								On your **host** machine:
 								- Any POSIX-shell (e.g. bash)
-												Add installation instructions

											
										
										
											2020-02-12 13:51:59 +01:00
+								- ffmpeg (with ffplay)
-												Add README

											
										
										
											2020-02-12 13:19:06 +01:00
+								- ssh
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
+								On your **reMarkable** nothing is needed, unless you want...
 								### Sub-second latency
-												Add video4linux2 support

											
										
										
											2020-04-14 10:46:07 +02:00
+								To achieve sub-second latency, you'll need [lz4](https://github.com/lz4/lz4)
-												Use lz4 instead of zstd, add prebuilt static library

											
										
										
											2020-03-17 23:44:55 +01:00
+								on your host and on your reMarkable.
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
-												Use lz4 instead of zstd, add prebuilt static library

											
										
										
											2020-03-17 23:44:55 +01:00
+								You can install `lz4` on your host with your usual package manager. On Ubuntu,
 								`apt install liblz4-tool` will do the trick.
-												Better documentation

											
										
										
											2020-03-12 00:17:13 +01:00
-												Use lz4 instead of zstd, add prebuilt static library

											
										
										
											2020-03-17 23:44:55 +01:00
+								On your **reMarkable** you'll need a binary of `lz4` build for the arm platform,
 								you can do this yourself by [installing the reMarkable toolchain](https://remarkablewiki.com/devel/qt_creator#toolchain)
 								and compiling `lz4` from source with the toolchain enabled, or you can use the
 								statically linked binary I have already built and put in this repo.
-												Graceful fallback to gzip if zstd is not present

											
										
										
											2020-02-12 14:47:47 +01:00
-												Add instructions to make lz4 executable

											
										
										
											2020-03-25 16:33:22 +01:00
+								Copy the `lz4` program to your reMarkable with
-												Don't use ~ in commands

											
										
										
											2020-04-06 23:19:54 +02:00
+								`scp lz4.arm.static root@10.11.99.1:/home/root/lz4`, make it executable with
 								`ssh root@10.11.99.1 'chmod +x /home/root/lz4'` and you're ready to go.
-												Simple troubleshooting stuff

											
										
										
											2020-03-30 21:35:15 +02:00
 								## Troubleshooting
 								Steps you can try if the script isn't working:
 								- [Set up an SSH key](#installation)
 								- Update `ffmpeg` to version 4.