Metadata-Version: 2.1
Name: matrix-webcam
Version: 0.4.1
Summary: Displays your webcam video feed in the console.
Home-page: https://github.com/joschuck/matrix-webcam
Author: Johannes Schuck
Author-email: jojoschuck@gmail.com
License: MIT License
        
        Copyright (c) 2022 Johannes Schuck
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: matrix webcam opencv skype
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
Provides-Extra: dev
Provides-Extra: deploy
License-File: LICENSE

# matrix-webcam

[![License MIT](https://img.shields.io/github/license/joschuck/matrix-webcam.svg)](https://github.com/joschuck/matrix-webcam/blob/main/LICENSE)
[![issues](https://img.shields.io/github/issues/joschuck/matrix-webcam.svg)](https://github.com/joschuck/matrix-webcam/issues)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)

This package displays your webcam video feed in the console.

Take your next video conference from within the matrix!

![matrix-webcam demo](https://raw.githubusercontent.com/joschuck/matrix-webcam/main/doc/matrix-webcam02.gif)

## Running it

Make sure you have Python and pip installed. Installation using pip:

    $ pip install matrix-webcam  # make sure it's in your PATH for it to run, alternatively use sudo
    $ matrix-webcam

Installing and running it from source:

    $ git clone https://github.com/joschuck/matrix-webcam.git
    $ cd matrix-webcam
    $ python -m pip install .
    $ matrix-webcam

Tip: Shrink your font size, it will look even more hacky

    usage: matrix-webcam [-h] [-l LETTERS] [-p PROBABILITY] [-u UPDATES_PER_SECOND]
    
    options:
    -h, --help            show this help message and exit
    -d DEVICE, --device DEVICE
                        Sets the index of the webcam if you have more than one webcam.
    -l LETTERS, --letters LETTERS
                        The number of letters produced per update.
    -p PROBABILITY, --probability PROBABILITY
                        1/p probability of a dispense point deactivating each tick.
    -u UPDATES_PER_SECOND, --updates-per-second UPDATES_PER_SECOND
                        The number of updates to perform per second.


## Can I use this for Teams/Zoom/Skype etc.? 

### For Windows/Mac Users
Yes! You can for example use [OBS Studio](https://obsproject.com/) ~~ together with the [Virtual Cam plugin](https://github.com/CatxFish/obs-virtual-cam) ~~ . Notice: obs-studio have officially provided virtual camera feature since version 26.0.0 , you can use it without installing this plugin.
Then all you need to do is select the virtual webcam in Teams/Zoom/Skype. 

### For Linux Users
First we need to make sure you have the [v4l2loopback kernel module](https://github.com/umlaeute/v4l2loopback) to create V4L2 loopback devices setup.
This module allows you to create "virtual video devices".
Normal (v4l2) applications will read these devices as if they were ordinary video devices, but the video will not be read from e.g. a capture card but instead it is generated by another application. 
It should be available in your distro's package manager.
Under Ubuntu install it using:

    $ sudo apt install -y v4l2loopback-dkms v4l2loopback-utils

Now we need to create a virtual v4l2 device (exclusive_caps=1 and YUV2 conversion is required by Chromium for the device to be recognized):

    $ sudo modprobe v4l2loopback devices=1 video_nr=42 card_label="Virtual Camera" exclusive_caps=1 max_buffers=2

Now we need to find the `xid` if the terminal window we will launch `matrix-webcam` in using 
    
    $ xdotool getactivewindow 
    79869947  # sample output

Optionally resize the terminal window to something reasonable from another terminal and then launch matrix webcam

    $ wmctrl -i -r 79869947 -e 0,300,300,1280,720  # in another terminal (2)

Now launch matrix-webcam

    $ matrix-webcam  # in the terminal that was just resized

Now launch the virtual device in terminal (2) - you need [Gstreamer](https://gstreamer.freedesktop.org/documentation/installing/on-linux.html?gi-language=c) for this, check the link on how to install it 

    $ gst-launch-1.0 ximagesrc xid=79869947 ! video/x-raw,framerate=30/1 ! videoconvert ! video/x-raw,format=YUY2 ! v4l2sink device=/dev/video42

That's it, your webcam should show up in Chromium, Teams, etc.!


## Development

I'd recommend creating a new virtual environment (if you are under Ubuntu install it using `sudo apt install python3-venv` using 

    $ python3 -m venv venv/
    $ source venv/bin/activate

Then install the dependencies using:

    $ pip install -e .[dev,deploy]

Setup pre-commit, too:

    $ pre-commit install

### TODO

* [x] Add Virtual webcam documentation for Linux/Gstreamer
* [x] add webcam selection
* [ ] Move to opencv-python-headless
* [ ] add tests

## License
This project is licensed under the MIT License (see the `LICENSE` file for details).
