Browse Source

Readme documentation

linux
parent
commit
a6058b7d2b
  1. 136
      README.md
  2. BIN
      images/UI-guide.png
  3. BIN
      images/WM_banner.gif
  4. BIN
      images/banner_02.png
  5. 0
      images/linux_about.png
  6. 0
      images/linux_main.png
  7. BIN
      images/video_device.png
  8. 0
      images/windows_about.png
  9. 0
      images/windows_main.png
  10. 8
      requirements.txt
  11. BIN
      screenshots/Screenshot from 2021-05-11 12-24-20.png

136
README.md

@ -1,50 +1,128 @@
# webcam_manager
# Webcam Manager
en avant les commits!
A simple program to loop your webcam on video calls.
[toc]
Features:
- Virtual webcam compatible with all video-call software
- Record loops and play them back as if they were from your webcam
- Generic name and interface to avoid scrutiny from co-workers and/or desktop monitoring
![webcam manager banner](images/banner_02.png)
## Installation
We are looking to package this as a bundled application, in the meantime to install and run the Python code:
### Windows
### Python dependencies
On Windows *Webcam Manager* relies on [OBS Studio](https://obsproject.com/) to create a virtual webcam that can be used in video-call software.
See `pyproject.toml` for requirements to install.
To install both *Webcam Manager* and OBS Studio, use the [installer](py/dist/WebcamManager_installer.exe)
### Linux
If OBS is already installed, you can use [webcam_manager.exe](py/dist/webcam_manager.exe)
On linux [v4l2loopback](https://github.com/umlaeute/v4l2loopback) is required to create a virtual webcam that can be used in call software.
### MacOS and Linux
```
sudo apt install v4l2loopback-dkms
```
Binaries and/or packages are not yet available. Please install using git and python as described below in [Development Installation](#development-installation).
The program starts the service automatically (this is why it asks for the sudo password at startup) to start manually:
## Operation
*Webcam Manager* is designed to be used on devices that may be monitored, for example through desktop monitoring (screenshots taken at random intervals).
For this reason nothing in the program window explicitly refers to looping the webcam. The application window looks as generic as possible. The few buttons are presented with no text and only icons usually associated with camera focus. This means that *Webcam Manager* may take some practice to operate. Fortunately, recording and playing webcam loops are the only functions available so the program is easy to learn.
![User-Interface Guide](images/UI-guide.png)
### Connect to call software
1. Launch *Webcam Manager*
2. Ensure the webcam is showing in the preview
3. Launch the video-call software
4. Select `Dummy video device` as a camera
- In browser-based video-calls (Jitsi, Google Meet, Zoom) this will be associated with the dialog asking for "permission" to use the camera. See example below in Jitsi and Firefox.
- In applications (Zoom, Microsoft Teams, etc) this is more likely to be found in video settings.
![example camera source dialog in Jitsi and Firefox with "Dummy video device" selected.](images/video_device.png)
### Recording a loop
1. Place your mouse cursor over the REC button
2. Click to start recording
3. Keep a static pose moving as little as possible
4. Click again to stop recording
### Playing a loop
Once a loop has been recorded.
1. Click the LOOP button or press the `Enter` key
2. The loop button is yellow when a loop is playing
3. Click the STOP button or press `Enter` to stop and display the live webcam again.
### Freezing the camera
To make the transition from loop back to a live camera, it can be useful to "freeze" the image and blame it on the connection.
Opening the About window with the **?** button freezes the picture for as long as the window is open.
## Development installation
1. Clone this repository
```bash
git clone git@gitlab.com:davidbenque/webcam_manager.git
cd webcam_manager
```
sudo modprobe v4l2loopback devices=1
```
### Windows
2. Install dependencies
If using poetry:
```bash
poetry install
```
else install the dependencies listed in `requirements.txt`
3. Virtual webcam dependencies
Required to create the virtual webcam that can be used in call software.
- On Windows [OBS Studio](https://obsproject.com/) should be installed.
On Windows Webcam Manager uses OBS virtual camera and requires [OBS Studio](https://cdn-fastly.obsproject.com/downloads/OBS-Studio-26.1.1-Full-Installer-x64.exe).
- On Linux [v4l2loopback](https://github.com/umlaeute/v4l2loopback) is required, to install:
```bash
sudo apt install v4l2loopback-dkms
```
v4l2loopback should be running before *Webcam Manager* is launched. If it not the program will launch it and ask for a sudo password.
If OBS is already installed, a binary of the application can be found at `py/dist/webcam_manager.exe`.
To launch v4l2loopback manually:
Otherwise a full installer which bundles OBS and Webcam Manager can be found at `py/dist/WebcamManager_installer.exe`.
``` bash
sudo modprobe v4l2loopback devices=1
```
4. Launch
#### Build on Windows
### How to build Windows binaries
To build a binary from the `webcam_manager.py` file, uncomment line 14 and 15:
```
```python
if getattr(sys, 'frozen', False) and hasattr(sys, '_MEIPASS'):
os.chdir(sys._MEIPASS)
```
then use `pyinstaller` to execute the following command:
```
```bash
pyinstaller --onefile --windowed --add-data "assets;assets" webcam_manager.py
```
@ -52,21 +130,13 @@ This will bundle all files and dependencies in a single file (`--onefile`). Any
This will create an `.exe` file in the `py/dist` directory along a `py/build` directory and a `webcam_manager.spec` file.
### MacOS
Coming soon...
## Usage
### Connect to call software
### Recording and looping
- buttons
- keybaord shortcuts
#### Distribution / Create an installer for windows
In order to create an installer that bundles OBS and Webcam Manager, [OBS Studio installer](https://cdn-fastly.obsproject.com/downloads/OBS-Studio-26.1.1-Full-Installer-x64.exe) is required.
Once downloaded move the installer in the `py/dist/inc` directory. This folder contains the external files bundled with your webcam application, such as the `logo.ico` and the `License.txt`.
We used [NSIS](https://nsis.sourceforge.io/Download) to create the installer; once you have NSIS installed, built the `py/dist/webcam_manager.exe` file as well as the `py/dist/inc/OBS-Studio-26.1.1-Full-Installer-x64.exe` file, compile the `py/dist/WM.nsi` with NSIS.
This should generate the `py/dist/WebcamManager_installer.exe`.

BIN
images/UI-guide.png

After

Width: 1080  |  Height: 950  |  Size: 212 KiB

BIN
images/WM_banner.gif

After

Width: 1350  |  Height: 1350  |  Size: 169 KiB

BIN
images/banner_02.png

After

Width: 1350  |  Height: 1350  |  Size: 178 KiB

0
screenshots/Screenshot from 2021-05-11 12-28-03.png → images/linux_about.png

Before

Width: 276  |  Height: 273  |  Size: 14 KiB

After

Width: 276  |  Height: 273  |  Size: 14 KiB

0
screenshots/Screenshot from 2021-05-11 12-27-54.png → images/linux_main.png

Before

Width: 446  |  Height: 543  |  Size: 96 KiB

After

Width: 446  |  Height: 543  |  Size: 96 KiB

BIN
images/video_device.png

After

Width: 573  |  Height: 319  |  Size: 37 KiB

0
screenshots/windows_about.png → images/windows_about.png

Before

Width: 269  |  Height: 259  |  Size: 8.9 KiB

After

Width: 269  |  Height: 259  |  Size: 8.9 KiB

0
screenshots/windows_main.png → images/windows_main.png

Before

Width: 427  |  Height: 521  |  Size: 17 KiB

After

Width: 427  |  Height: 521  |  Size: 17 KiB

8
requirements.txt

@ -0,0 +1,8 @@
imutils==0.5.4
numpy==1.20.1; python_version >= "3.7"
opencv-contrib-python==4.5.1.48; python_version >= "3.6"
pillow==8.1.2; python_version >= "3.6"
pysimplegui==4.37.0
pyvirtualcam==0.5.0
tk==0.1.0
toml==0.10.2; (python_version >= "2.6" and python_full_version < "3.0.0") or (python_full_version >= "3.3.0")

BIN
screenshots/Screenshot from 2021-05-11 12-24-20.png

Before

Width: 903  |  Height: 659  |  Size: 121 KiB

Loading…
Cancel
Save