{"id":15197073,"url":"https://github.com/leonlaser/pi-asciicam","last_synced_at":"2025-06-20T10:05:12.885Z","repository":{"id":144641083,"uuid":"102269435","full_name":"leonlaser/pi-asciicam","owner":"leonlaser","description":"A live stream ASCII webcam server for Raspberry Pis using websockets, written in go.","archived":false,"fork":false,"pushed_at":"2018-10-27T22:18:30.000Z","size":31874,"stargazers_count":22,"open_issues_count":9,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T12:44:10.278Z","etag":null,"topics":["ascii-art","docker","go","golang","raspberry-pi","raspberry-pi-camera","raspberrypi","video-processing","video-streaming-server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leonlaser.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-03T14:15:03.000Z","updated_at":"2024-07-01T01:46:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"ed23fe50-b921-41ab-989b-f0e5fe895ce2","html_url":"https://github.com/leonlaser/pi-asciicam","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonlaser%2Fpi-asciicam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonlaser%2Fpi-asciicam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonlaser%2Fpi-asciicam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonlaser%2Fpi-asciicam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonlaser","download_url":"https://codeload.github.com/leonlaser/pi-asciicam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238608315,"owners_count":19500356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii-art","docker","go","golang","raspberry-pi","raspberry-pi-camera","raspberrypi","video-processing","video-streaming-server"],"created_at":"2024-09-28T00:41:05.632Z","updated_at":"2025-02-13T06:33:24.889Z","avatar_url":"https://github.com/leonlaser.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/leonlaser/pi-asciicam)](https://goreportcard.com/report/github.com/leonlaser/pi-asciicam)\n\n# Raspberry Pi ASCII-Cam\n\n![pi-asciicam demo GIF](demo.gif)\n\nThe __pi-ascii-cam__ project allows you to create an ASCII live camera stream from a Raspberry Pi with an attached Raspberry Pi Camera or any MJPEG stream.\nIt is utilizing `raspivid` to convert its MJPEG stream into an ASCII character representation and transport them over a websocket.\n\nThe servers are written in golang, the client is simply HTML/CSS/JavaScript.\n\n## Binaries\n\nYou can find binaries for Linux and MacOS in `bin/`.\n\nOn plattforms other than the Raspberry Pi, `asciicam-server` will only be able to do a conversion from MJPEG to ASCII from an external network source. See [Receive an external MJPEG stream](#receive-an-external-mjpeg-stream) on how to do that.\n\nI did not test all binaries. Just `linux-arm` and `macos-amd64`.\n\n## Start the ASCII stream server\n\n    ./asciicam-server\n\nYou are now able to connect to a websocket on port 8000 on all network interfaces. There is already an example HTML/JavaScript client you can host: `asciicam-server/example_client.html`. Use a webserver of your choice on the same machine. The client will connect automatically to the websocket.\n\nShow all possible options and defaults:\n\n    ./asciicam-server --help\n\n## Serve clients from other machines\n\n`asciicam-server` can server multiple clients, but a single Raspberry Pi could be quickly overwhelmed. Also you may not want to serve your stream directly from your office or home server.\n\nThe `asciicam-imux` is a very simple inverse multiplexer, which connects to your `asciicam-server`, splits the websocket stream for multiple clients and serves them.\n\nTo start a single server on an external machine just run:\n\n    ./asciicam-imux -s 10.0.0.10:8000 -p 88888\n\n__-s__ ip and port where `asciicam-server` is running\n\n__-p__ the port you want your clients to connect to\n\n### asciicam-imux docker image\n\nYou can use the existing Dockerfile to build your own image or use the ones already available on hub.docker.com.\n\n* [leonlaser/pi-asciicam-imux](https://hub.docker.com/r/leonlaser/pi-asciicam-imux/)\n* [leonlaser/pi-asciicam-imux-arm](https://hub.docker.com/r/leonlaser/pi-asciicam-imux-arm/) for usage on a Raspberry Pi\n\nRun the docker image\n\n    docker run -p 9000:9000 -e PORT=9000 -e SOURCE=10.0.0.10:8000 leonlaser/pi-asciicam-imux\n\n## Receive an external MJPEG stream\n\nThe `asciicam-server` calls `raspvid` directly and uses its MJPEG stream on stdout to generate the ASCII frames.\n\nA Raspberry Pi Zero is quickly overwhelmed when converting 10 frames per second or more and serving a websocket connection.\n\nTo remove the load of converting frames, you can use your Raspberry Pi to only start `raspivid` itself and stream the MJPEG over the network with netcat:\n\n    raspivid -o - -w 320 -h 200 -n -t 0 -cd MJPEG -fps 25 | nc -lkv4 5001\n\nIn my expierence netcat somehow gives up at some point. A better alternative for me was to use `ncat`, which belongs to `nmap` and will be installed with it:\n\n    raspivid -o - -w 320 -h 200 -n -t 0 -cd MJPEG -fps 25 | ncat -k -l 5001\n\nNow use `asciicam-server` to connect and open a new websocket:\n\n    ./asciicam-server -net 10.0.0.1:5001\n\nNow your Raspberry Pi only sends a video stream and another machine running `asciicam-server` can convert your video and serve the websocket connections.\n\nBased on your needs, your clients can directly connect to your `asciicam-server` or you can use `asciicam-imux` to scale:\n\n-\u003e Raspberry Pi running `raspivid` streams to -\u003e a Machine running `asciicam-server` serving a websocket, which gets distributes by -\u003e n-Machines running `asciicam-imux` in a docker swarm or using a loadbalancer for your clients to connect to.\n\n## Using an USB webcam\n\nBecause `asciicam-server` is able to retrieve any MPJEG stream, you can use any source and convert it to an ASCII video. Here is an example on using `avconv` to access you local video device and start an MJPEG stream:\n\n    avconv -f video4linux2 -s 320x200 -i /dev/video0 -r 15 -f mjpeg tcp://0.0.0.0:5001?listen\n\nNow use `asciicam-server` with the `-net` parameter to connect.\n\n# Client\n\nWithout a client nobody can see your live stream. You can use two different files. As mentioned earlier, there is a really simple client to show you what is going on: `asciicam-server/example_client.html`.\n\n`webclient/webclient.html` is a bit more advanced, allowing you to connect to any websocket stream by entering an address. It is using requestAnimationFrame() and shows the frames per second, received through the websocket connection. It is very helpfull for debugging your setup.\n\n# Build\n\nThis section is mostly for myself. But if you want to built your own setup for streaming your video feed, want to modify the sources and deploy them on different machines, help yourself:\n\n## Compile go sources\n\nSee makefile.\n\n## Build docker images\n\nSee makefile.\n\n# But why?\n\nI was looking for project to learn more about golang, Docker, Docker Swarm and Raspberry Pi.\n\n# Thanks\n\nA thank you goes to [idevelop](https://github.com/idevelop) for his awesome [ascii-camera](https://github.com/idevelop/ascii-camera). My image to character conversion is simply a port of his [ascii.js](https://github.com/idevelop/ascii-camera/blob/master/script/ascii.js), which features some links to every step of his image pre-processing before converting it to actual characters.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonlaser%2Fpi-asciicam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonlaser%2Fpi-asciicam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonlaser%2Fpi-asciicam/lists"}