Help us shape the future of Go! Take the 2026 Go Developer Survey

screenshot

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 20, 2022 License: GPL-3.0 Imports: 24 Imported by: 1

README

ScreenShot

golang GoDoc Go Report Issues Size Tag View examples License

Purpose

Sometimes you don't want just standard web links in your web presentation but a preview image showing the page you're linking to. That is where this package comes in. It generates – by way of calling the external Chrome browser – an image of the web page a given URL addresses. Those image files are stored locally and may be used as often as you want without additional external network traffic.

Installation

You can use Go to install this package for you:

go get github.com/mwat56/screenshot

After that you can import it the usual Go way to use the library.

Usage

There are only two functions you have to worry about:

// SetImageDir sets the directory to use for storing the generated
// screenshot images.
//
// If `aDirectory` is empty or invalid the system's temp directory is used.
//
// `aDirectory` The directory to store the generated images.
func SetImageDir(aDirectory string) { … }

This function should be called before any other one to make sure the generated screenshots end up where you want them to be. The default is the system's temp directory (e.g. /tmp under GNU/Linux).

To actually create the screenshot image you'd call:

// CreateImage generates an image of `aURL` and stores it in `ImageDir()`,
// returning the file name of the saved image or an error in case of problems.
//
//	`aURL` The address of the web page to process.
func CreateImage(aURL string) (string, error) { … }

The returned string is the name of the generated image file (without its path). If you combine it with the directory returned by ImageDir() you get the complete path/filename to locally access the image.

Generating a screenshot image usually takes between one and five seconds, depending on the actual web-page in question; however, it can take considerably longer. To avoid hanging the program the CreateImage() function uses a timeout of half a minute.

And, finally, not all web-pages can be rendered properly and turned into an image. In case of errors (like network-errors or problem while storing the image file) CreateImage() returns an empty filename and an error.

There are a couple more functions (mostly property GETters and SETters) which you will probably barely need; for details refer to the source code documentation.

Libraries

The Go library controlling a headless instance of the Chrome browser

is required for this package to work. Under Linux this browser is usually part of your distribution (as chromium-browser).

To resize the screenshot if required by the ImageHeight()/ImageWidth() values the

must be part of your Go installation (if not, run: go get -u golang.org/x/image/draw).

Example

In the source code's sub-directory app/ there's a demo program (screenshot.go) allowing you to generate a screenshot image of an URL given on the commandline.

To run it call e.g.

#> cd app
#> go build screenshot.go
#> ./screenshot

It will show you all available commandline options e.g.:

Usage: ./screenshot [OPTIONS]

-bc
	allow the browser to handle web cookies (default "false")
-be
	skip sites with Certificate errors (default "false")
-bm
	let browser emulate a mobile device (default "false")
-bs
	let browser show scrollbars if available (default "false")
-bt int
	max. time (seconds) allowed to process a single web page (default 32)
-id string
	directory for storing the screenshot image (default "/tmp")
-ih int
	max. height of the screenshot image (default 768)
-iq int
	quality of the screenshot image (default 75)
-is float
	the browser's scale factor for the screenshot image
-iw int
	max. width of the screenshot image (default 896)
-ja string
	name of text-file that contains sites better avoiding JavaScript (default "/home/matthias/devel/Go/src/github.com/mwat56/screenshot/app/hostsavoidjs.list")
-jn string
	name of text-file that contains sites needing JavaScript (default "/home/matthias/devel/Go/src/github.com/mwat56/screenshot/app/hostsneedjs.list")
-jp navigator.platform
	Identifier the JavaScript navigator.platform should use (default "Linux x86_64")
-js
	allow browser's use of JavaScript (default "false")
-ju string
	description of the UserAgent the browser should report (default "Mozilla/5.0 (X11; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0")
-u string
	(_required_) the URL for the browser's screenshot (default "")
-v	verbose (default "false")

As noted before you'll only need the -u string option, obviously.

You can use this program to generate screenshot images "by hand" and fiddle with the various commandline options to see what difference it makes if you change them.

History

Prior to this a few years back I wrote the pageview package which used the external wkhtmltoimage program; and in most cases it worked just fine. However, once in a while wkhtmltoimage produced a segmentation fault (core dumped) – reproducible. For a while I thought I could live with it, but over time it happened more often (i.e. with additional URLs). Fiddling around with various commandline options provided no improvement. In the end I started to look around, searching for alternative approaches – short of writing my own URL retrieval and rendering system. That's when I found ChromeDP and hence this package.

Licence

    Copyright © 2022 M.Watermann, 10247 Berlin, Germany
                    All rights reserved
                EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.

Documentation

Overview

Package screenshot implements a web page link preview (snapshot image). 

Copyright © 2022 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CertErrors 

func CertErrors() bool

CertErrors returns whether to skip sites with Certificate errors; defaults to `false` for historic reasons.

func Cookies 

func Cookies() bool

Cookies returns whether to allow web cookies during page retrieval; defaults to `false` for safety and speed reasons.

func CreateImage 

func CreateImage(aURL string) (string, error)

CreateImage generates an image of `aURL` and stores it in `ImageDir()`, returning the file name of the saved image or an error in case of problems. 

`aURL` The address of the web page to process.

func HostsAvoidJS 

func HostsAvoidJS() string

HostsAvoidJS returns the name of the path/file containing hosts/domains where to avoid running JavaScript.

NOTE: This value is used only if the `JavaScript()` option is set `true`.

func HostsNeedJS 

func HostsNeedJS() string

HostsNeedJS returns the name of the path/file containing hosts/domains requiring JavaScript to be active/working.

NOTE: This value is used only if the `JavaScript()` option is set `false`.

func ImageAge 

func ImageAge() time.Duration

ImageAge returns the maximum age of locally stored screenshot images.

func ImageDir 

func ImageDir() string

ImageDir returns the directory to store the generated screenshot images.

func ImageHeight 

func ImageHeight() int

ImageHeight is the max. height of the virtual screen used to render. The default value is `768`.

NOTE: This is the max. height of the screenshot. Depending on the actual web-site and its rendering by the running 'Chrome' instance the generated image's height could be less.

The value `0` (zero) renders the entire page top to bottom, calculating the actual height from the page content.

func ImageQuality 

func ImageQuality() int

ImageQuality returns the desired image quality.

func ImageScale 

func ImageScale() float64

ImageScale returns the virtual browser's scale factor for the generated screenshot image.

func ImageType 

func ImageType() string

ImageType returns the type/format of the screenshot file generated.

NOTE: The image type/format depends on the given `ImageQuality()`: `quality == 100` results in a `png` image, `quality < 100` results in a `jpeg` image.

If the URL to shoot points to an image file (".gif", ".jpeg", ".jpg", ".png", ".svg") the result of this function might be wrong because the actually generated image depends on the type of the requested image.

func ImageWidth 

func ImageWidth() int

ImageWidth is the width in pixels of the imaginary screen used to render. The default value is `1024`.

NOTE: This is the max. width of the screenshot. Depending on the actual web-site and its rendering by the running 'Chrome' instance the generated image could be smaller.

func JavaScript 

func JavaScript() bool

JavaScript returns whether to allow JavaScript during page retrieval; defaults to `false` for safety and speed reasons.

func MaxProcessTime 

func MaxProcessTime() time.Duration

MaxProcessTime returns the timeout (in seconds) used to retrieve & render a requested web page.

func Mobile 

func Mobile() bool

Mobile returns whether the virtual browser should emulate a mobile device.

func PathFile 

func PathFile(aURL string) string

PathFile returns the complete local path/file of `aURL`.

NOTE: This function does not check whether the file for `aURL` actually exists in the local filesystem. 

`aURL` The address of the web page to process.

func Platform 

func Platform() string

Platform returns the platform `navigator.platform` should return.

NOTE: This value is used only if the `JavaScript()` option is set `true`.

func Scrollbars 

func Scrollbars() bool

Scrollbars returns whether the virtual browser will show scrollbars (if available in web-page).

func SetCertErrors 

func SetCertErrors(anAllow bool)

SetCertErrors determines whether to skip sites with certificate errors. 

`anAllow` If `false` (i.e. the default) all web-sites will be processed

regardless of certificate errors.

func SetCookies 

func SetCookies(anAllow bool)

SetCookies determines whether to allow web cookies during page retrieval or not. 

`anAllow` If `false` (i.e. the default) no cookies will be available

during page retrieval, otherwise (i.e. `true`) they will be used.

func SetHostsAvoidJS 

func SetHostsAvoidJS(aFilename string)

SetHostsAvoidJS configures the name of the file containing hosts/domains where to avoid running JavaScript.

NOTE: This value is used only if the `JavaScript` option is set `true`. An invalid filename disables the feature. 

`aFilename` The path/filename of sites with JavaScript to avoid.

func SetHostsNeedJS 

func SetHostsNeedJS(aFilename string)

SetHostsNeedJS configures the name of the file containing hosts/domains requiring JavaScript to be active/working.

NOTE: This value is used only if the `JavaScript()` option is set `false`. An invalid filename disables the feature. 

`aFilename` The path/filename of sites with required JavaScript.

func SetImageAge 

func SetImageAge(aMaxAge time.Duration)

SetImageAge sets the maximum age of locally stored screenshot images before they might get updated by a new call to `CreateImage(…)`.

Usually you'll want this property at its default value (`0`, zero) which disables an age check because usually you want an image of the page at the time you linked to it. 

`aMaxAge` is the age a page image can have before

requesting it again.

func SetImageDir 

func SetImageDir(aDirectory string)

SetImageDir sets the directory to use for storing the generated screenshot images.

If `aDirectory` is empty or invalid the system's temp directory is used. 

`aDirectory` The directory to store the generated images.

func SetImageHeight 

func SetImageHeight(aHeight int)

SetImageHeight sets the height in pixels of the screenshot images to generate. The default value is `768`.

NOTE: This is the max. height of the screenshot. Depending on the actual web-site and its rendering by the running `Chrome` instance the generated image's height could be less.

Setting this value to `0` will result in an image containing the whole web-page (which might be quite lang); so the actual height of the generated screenshot would be unpredictable. 

`aHeight` The new height of the images to generate.

func SetImageQuality 

func SetImageQuality(aQuality int)

SetImageQuality changes the quality of the screenshot image to be generated. Values supported between `1` and `100`; default is `75`. 

`aQuality` the new desired image quality.

func SetImageScale 

func SetImageScale(aFactor float64)

SetImageScale sets the virtual browser's scale factor for the generated screenshot image. 

`aFactor` the new scale factor; `0` disables scaling.

func SetImageWidth 

func SetImageWidth(aWidth int)

SetImageWidth sets the width of the images to generate. The default value is `1024`.

NOTE: This is the max. width of the screenshot. Depending on the actual web-site and its rendering by the running 'Chrome' instance the generated image could be smaller. 

`aWidth` The new width of the images to generate.

func SetJavaScript 

func SetJavaScript(anAllow bool)

SetJavaScript determines whether to allow JavaScript during page retrieval or not. 

`anAllow` If `false` (i.e. the default) no JavaScript will be available

during page retrieval, otherwise (i.e. `true`) it will be activated.

func SetMaxProcessTime 

func SetMaxProcessTime(aProcessTime time.Duration)

SetMaxProcessTime sets the timeout used to retrieve & render a requested web page.

NOTE: A wrong (i.e. negative) value and `0` (zero) resets the timeout value to its default od 32 seconds. 

`aProcessTime` The new max. seconds allowed to process a web page.

func SetMobile 

func SetMobile(aForceMobile bool)

SetMobile set whether to emulate mobile device. This includes viewport meta tag, overlay scrollbars, text autosizing and more. 

`aForceMobile`

func SetPlatform 

func SetPlatform(aPlatform string)

SetPlatform sets the platform `navigator.platform` should return.

NOTE: This value is used only if the `JavaScript()` option is set `true`. 

`aPlatform` The platform identifier to use for `navigator.platform`.

func SetScrollbars 

func SetScrollbars(aScrollbar bool)

SetScrollbars sets whether the virtual browser will show scrollbars (if available in web-page). 

`aScrollbar` Flag whether to show scrollbars (if available).

func SetUserAgent 

func SetUserAgent(aAgent string)

SetUserAgent changes the current `User Agent` setting to `aAgent`.

NOTE: This value is used only if the `JavaScript()` option is set `true`. 

`aAgent` The new `User Agent` setting.

func String 

func String() string

String returns a string of lines showing the currently configured screenshot options.

func UserAgent 

func UserAgent() string

UserAgent returns the current `User Agent` setting.

NOTE: This value is used only if the `JavaScript()` option is set `true`.

Types

type ScreenshotParams 

type ScreenshotParams struct {

	// Flag whether certificate errors should be ignored.
	CertErrors bool

	// Allow use of web cookies
	Cookies bool

	// Path/filename of a list of web hosts/domains where JavaScript
	// running should be avoided (defaults to a file in user's homedir).
	HostsAvoidJS string

	// Path/filename of a list of web hosts/domains where JavaScript
	// is required to work (defaults to a file in user's homedir).
	HostsNeedJS string

	// Max. age of cached page screenshot images (in seconds).
	ImageAge time.Duration

	// Directory to store the generated screenshot images.
	ImageDir string

	// Max. height of the screenshot image to generate.
	ImageHeight int

	// Quality (in percent) of the screenshot image to generate.
	ImageQuality int

	// The virtual browser's scale factor value.
	// 0 disables the override.
	ImageScale float64

	// Max. width of the screenshot image to generate.
	ImageWidth int

	// Flag whether to allow JavaScript in retrieved pages.
	JavaScript bool

	// Timeout duration (seconds) for page processing
	MaxProcessTime time.Duration

	// Flag whether to emulate a mobile device or not.
	// This includes viewport meta tag, overlay scrollbars, text
	// autosizing and more.
	Mobile bool

	// The identifier the JavaScript `navigator.platform` should return.
	Platform string

	// Flag whether to show the scraped web-page's scrollbars.
	Scrollbars bool

	// User Agent to use when queuing external sites.
	UserAgent string
}

ScreenshotParams bundles all available configuration Options and pass them to the `Setup()` function in a single call.

func Options 

func Options() (rOptions *ScreenshotParams)

Options returns the currently configured screenshot options.

func Setup 

func Setup(aOptions *ScreenshotParams) (rOptions *ScreenshotParams)

Setup uses `aOptions` to configure the runtime options for taking screenshots.

NOTE: While it is perfectly legal (from Go's point of view) to omit those fields you don't care about please be aware that those missing fields will nevertheless be set (by `Go`): with the respective data type's default value. And since there's no way to distinguish the automatically set default value of a missing field from a user provided value you have to handle such a situation carefully. Depending on the number of options you want to set you might want to prefer calling the various `SetXxxx()` functions (if there are less than half of the available options to set). Or – if you want to set the majority of the options – you'd provide the options you do not want to change with their already existing default values by calling the respective Getter function of the option in question, like: 

myOptions := &ScreenshotParams{
	// set fields …
	ImageHeight: myHeightValue,
	ImageQuality:  myQualityValue,
	// …
	// say, you don't want to change the width option
	ImageWidth:  screenshot.ImageWidth(),
}
screenshot.Setup(myOptions)
// continue with your program …

`aOptions` The screenshot options tu use.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.