{"id":15287147,"url":"https://github.com/vivocha/hands-free-chrome","last_synced_at":"2025-05-07T04:02:12.641Z","repository":{"id":57260624,"uuid":"93862517","full_name":"vivocha/hands-free-chrome","owner":"vivocha","description":"Headless Chrome utilities","archived":false,"fork":false,"pushed_at":"2018-12-14T03:16:07.000Z","size":108,"stargazers_count":6,"open_issues_count":4,"forks_count":0,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-03T23:02:40.011Z","etag":null,"topics":["capture","chrome","headless","nodejs","screenshot"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vivocha.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}},"created_at":"2017-06-09T13:41:12.000Z","updated_at":"2023-06-29T04:55:31.000Z","dependencies_parsed_at":"2022-08-25T01:41:02.677Z","dependency_job_id":null,"html_url":"https://github.com/vivocha/hands-free-chrome","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivocha%2Fhands-free-chrome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivocha%2Fhands-free-chrome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivocha%2Fhands-free-chrome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivocha%2Fhands-free-chrome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vivocha","download_url":"https://codeload.github.com/vivocha/hands-free-chrome/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252810269,"owners_count":21807759,"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":["capture","chrome","headless","nodejs","screenshot"],"created_at":"2024-09-30T15:24:50.544Z","updated_at":"2025-05-07T04:02:12.445Z","avatar_url":"https://github.com/vivocha.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hands-free Chrome\n\n[Headless Chrome](https://developers.google.com/web/updates/2017/04/headless-chrome) utilities.\n\n\n\n[![travis build](https://img.shields.io/travis/vivocha/hands-free-chrome.svg)](https://travis-ci.org/vivocha/hands-free-chrome)\n[![Coverage Status](https://coveralls.io/repos/github/vivocha/hands-free-chrome/badge.svg?branch=master)](https://coveralls.io/github/vivocha/hands-free-chrome?branch=master)\n[![npm version](https://img.shields.io/npm/v/hands-free-chrome.svg)](https://www.npmjs.com/package/hands-free-chrome)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\nCurrent included features:\n- capture screenshots of web pages, generating png and/or pdf files\n- resize png screenshots to generate thumbnails\n- run as Microservice using Docker (Dockerfile included)\n- Web API\n\n\n\n\n## Prerequisites\n\n\n[Chrome version \u003e 59.x](https://www.google.com/chrome/browser/desktop/index.html) must be installed.\n\n**WARNING**: due to a [known bug](https://bugs.chromium.org/p/chromium/issues/detail?id=713268) of Chrome 59 on macOS closing tabs doesn't work properly on that platform. See API documentation below for more info.\n\n**Node.js version \u003e 8.1.0**\n\n\n---\n## Quick Start\n\n```sh\n$ npm install hands-free-chrome\n```\nthen:\n\n```js\nconst HandsfreeChrome = require('hands-free-chrome');\n\nlet chrome = new HandsfreeChrome();\n\n//capture a screenshot as png\nchrome.captureScreenshot('\u003cA VALID WEB PAGE URL\u003e')\n  .then(name =\u003e console.log(`Created file: ${name}.png`))\n  .catch(err =\u003e console.log(err));\n```\n___\n\n## API\n\n**`new HandsfreeChrome( [options] )`**\n\nConstructor.\n\nInstantiate a new HandsFreeChrome.\n\n`options` is an *optional* object with the following properties:\n\n- `port` -  integer, Headless Chrome listening port, default: `9999`;\n- `autoSelectChrome` -  boolean, enable/disable autoselection of installed Chrome, default: `true` (recommended);\n- `chromeFlags` -  array of strings, Headless Chrome configuration, default: `['--disable-gpu', '--headless']`;\n\n---\n**`HandsfreeChrome # captureScreenshot(url, [options])`**\n\nCapture a screenshot of a web page and create image files.\n\nParams:\n\n- `url` - string, a valid web page URL;\n- `options` - (optional) Object, screenshot configuration, with the following properties:\n    - `outputType` - (optional) string, specifies the output file type, can be: `png` (default), `pdf` or `both`;\n    - `outputDir` - (optional) string, directory path to contain generated screenshots. Default is `\u003ccwd\u003e/screenshots`;\n    - `metrics` - object, screen metric properties, defaults to `DesktopScreenMetrics`, see the dedicated section below;\n    - `thumbnail` - (optional) object `{ width: \u003cpx\u003e, height: \u003cpx\u003e }`, if used produces a resized png of the screenshot of the specified dimensions. It works only if `outputType` is `png`.\n\n---\n**`HandsfreeChrome # captureScreenshotAsStream(url, [options])`**\n\nCapture a screenshot of a web page and return a data readable stream.\n\nParams:\n\n- `url` - string, a valid web page URL;\n- `options` - (optional) Object, screenshot configuration, with the following properties:\n    - `outputType` - (optional) string, specifies the image file type, can be: `png` (default) or `pdf`;\n    - `metrics` - object, screen metric properties, defaults to `DesktopScreenMetrics`, see the dedicated section below.\n---\n\n\n**`HandsfreeChrome # captureScreenshotAsStreamByTab(url, [options])`**\n\nCapture a screenshot of a web page *opening and closing a new browser tab* and return a data readable stream.\n\n**WARNING**: due to a [known bug](https://bugs.chromium.org/p/chromium/issues/detail?id=713268) of Chrome 59 on macOS closing tabs doesn't work properly on that platform. To use this method please use Linux or Docker ;)\n\nParams:\n\n- `url` - string, a valid web page URL;\n- `options` - (optional) Object, screenshot configuration, with the following properties:\n    - `outputType` - (optional) string, specifies the image file type, can be: `png` (default) or `pdf`;\n    - `metrics` - object, screen metric properties, defaults to `DesktopScreenMetrics`, see the dedicated section below.\n---\n\n\n\n**`HandsfreeChrome # resizePng(pngStream, [size])`**\n\nResize a png image given its stream and a size.\n\nParams:\n\n- `pngStream` - Readable image stream;\n- `size` - (optional) object `{ width: \u003cpx\u003e, height: \u003cpx\u003e }`, the size of the required thumbnail. If not provided, default is: `{ width: 320, height: 200 }`.\n\n---\n### Metrics Object\n\nMetrics Object specifies some configuration options for Headless Chrome, like the browser window size, mobile emulation and so on. See [Chrome DevTools Protocol page](https://chromedevtools.github.io/devtools-protocol/tot/Emulation/) for more info.\n\nSupported params are: \n```js\n  width: number;\n  height: number;\n  deviceScaleFactor: (optional) number;\n  mobile: (optional) boolean;\n  fitWindow: (optional) boolean;\n```\nIf `metrics` param is not specified or undefined in the above methods calls, then it defaults to: `DesktopScreenMetrics`, set as follows:\n\n```js\n{\n  width: 1920,\n  height: 1080,\n  deviceScaleFactor: 0,\n  mobile: false,\n  fitWindow: false\n}\n```\n\n\n\n---\n## Web API Server\nA Web API Server is now included in the package in order to expose the lib as Microservice.\n\nAfter installing the npm package, running:\n\n```sh\n$ node ./node_modules/hands-free-chrome/dist/api\n```\n\nit starts a HTTP server at `localhost`, default port: `8000`.\n\nTo start the API server listening at a different port, just set the `PORT` environment variable.\n\nTo start the underlying Headless Chrome instance at a different port, set the `CHROME_PORT` environment variable (default is `9222`).\n\n\nExample:\n\n```sh\n$ PORT=8080 node ./node_modules/hands-free-chrome/dist/api\n```\n### Endpoints\n\n**POST /screenshots/actions/capture**\n\nSends a request to capture a screenshot.\nIt returns a response with a base64 encoded stream body with `Content-Type` equal to `image/png` or `application/pdf`.\n\nPOST body must be a JSON object with the following properties:\n\n- `url`: (Required) string, complete URL of the page to capture;\n- `type`: (Optional) string, image type for the requested screenshot: `png` or `pdf` (default is `png`);\n- `thumbnail` - (optional) object in the form of `{ width: \u003cpx\u003e, height: \u003cpx\u003e }` to generate a thumbnail. If not provided a \"full\" screenshot is returned. It works only if `type` is `png`.\n\nExample:\n\n```js\n{\n  \"url\": \"https://en.wikipedia.org/wiki/Node.js\",\n  \"type\": \"png\"\n}\n```\n\n\n**GET /screenshots/{url}[?thumbnail=width,height]**\n\nGets a screenshot thumbnail for the specified `url` path parameter.\nIt returns a response with a base64 encoded stream body with `Content-Type` equal to `image/png`. The thumbnail will have the size \nspecified by the `thumbnail` query param.\n\nPath parameter is:\n\n- `url` - (required) string, complete **URL percent-encoding** URL of the page to capture;\n\nQuery parameter is:\n\n- `thumbnail` - (optional) string in the form of `width,heigth` to generate a thumbnail of the specifies size. If not provided default is `160,100`.\n\nExample:\n\n```sh\ncurl --request GET \\\n  --url 'http://\u003cyour-server\u003e/screenshots/http%3A%2F%2Fwww.corriere.it?thumbnail=160%2C100' \\\n  --header 'content-type: application/json'\n```\n\n---\n\n# Docker\n\nThanks to the provided `Dockerfile` it is possible to run this component + API server as a Microservice, exposing the Web API endopoints listed above.\n\nIn order to \"dockerize\" the microservice, from the project root directory:\n\n1. build the image: \n\n```sh\n$ docker build -t vvc/hfchrome .\n```\n\n2. run the container (as default, API server is configured to listen at port 8000, see `Dockerfile`):\n\n```sh\n$ docker run --name hfc -p 8000:8000 -d --privileged vvc/hfchrome\n```\n\n---\n# Docker Compose\n\nThis project also includes a Docker Compose configuration in order to launch a composition of 3 microservices, as follows:\n\n![Docker Microservices](https://github.com/vivocha/hands-free-chrome/raw/master/assets/img/hfc-ms.png)\n\n- **two Hands-free Chrome** nodes (hfc1, hfc2) to capture screenshots;\n- **one NGINX** instance (hfc-nginx-lb) to act as a load balancer between the two nodes; it is also configured to cache images in order to avoid performing the same screenshot capture tasks in a given time window (see `nginx/nginx.conf` file).\n\nTo execute composed services, run the following commands in the project root directory:\n\n```sh\n$ docker-compose build\n$ docker-compose up -d\n```\n\nNGINX is configured to listen at port 8000, exposed APIs are the same as described above.\n\n\n---\n\nLicense - \"MIT License\"\n-----------------------\n\nCopyright (c) 2017 Vivocha S.p.A.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivocha%2Fhands-free-chrome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvivocha%2Fhands-free-chrome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivocha%2Fhands-free-chrome/lists"}