Camera¶

Classes and functions for reading and writing camera streams.

A camera may be used to document participant responses on video or used by the experimenter to create movie stimuli or instructions.

Overview¶

Details¶

class psychopy.hardware.camera.Camera(device=0, mic=None, cameraLib='ffpyplayer', frameRate=None, frameSize=None, bufferSecs=4, win=None, name='cam')[source]¶

Class for displaying and recording video from a USB/PCI connected camera.

This class is capable of opening, recording, and saving camera video streams to disk. Camera stream reading/writing is done in a separate thread, allowing capture to occur in the background while the main thread is free to perform other tasks. This allows for capture to occur at higher frame rates than the display refresh rate. Audio recording is also supported if a microphone interface is provided, where recording will be synchronized with the video stream (as best as possible). Video and audio can be saved to disk either as a single file or as separate files.

GNU/Linux is supported only by the OpenCV backend (cameraLib=’opencv’).

Parameters:

• device (str or int) – Camera to open a stream with. If the ID is not valid, an error will be raised when open() is called. Value can be a string or number. String values are platform-dependent: a DirectShow URI or camera name on Windows, or a camera name/index on MacOS. Specifying a number (>=0) is a platform-independent means of selecting a camera. PsychoPy enumerates possible camera devices and makes them selectable without explicitly having the name of the cameras attached to the system. Use caution when specifying an integer, as the same index may not reference the same camera every time.

• mic (Microphone or None) – Microphone to record audio samples from during recording. The microphone input device must not be in use when record() is called. The audio track will be merged with the video upon calling save(). Make sure that Microphone.maxRecordingSize is specified to a reasonable value to prevent the audio track from being truncated. Specifying a microphone adds some latency to starting and stopping camera recording due to the added overhead involved with synchronizing the audio and video streams.

• frameRate (int or None) – Frame rate to record the camera stream at. If None, the camera’s default frame rate will be used.

• frameSize (tuple or None) – Size (width, height) of the camera stream frames to record. If None, the camera’s default frame size will be used.

• cameraLib (str) – Interface library (backend) to use for accessing the camera. May either be ffpyplayer or opencv. If None, the default library for the recommended by the PsychoPy developers will be used. Switching camera libraries could help resolve issues with camera compatibility. More camera libraries may be installed via extension packages.

• bufferSecs (float) – Size of the real-time camera stream buffer specified in seconds (only valid on Windows and MacOS). This is not the same as the recording buffer size. This option might not be available for all camera libraries.

• win (Window or None) – Optional window associated with this camera. Some functionality may require an OpenGL context for presenting frames to the screen. If you are not planning to display the camera stream, this parameter can be safely ignored.

• name (str) – Label for the camera for logging purposes.

Examples

Opening a camera stream and closing it:

camera = Camera(device=0)
camera.open()  # exception here on invalid camera
camera.close()

Recording 5 seconds of video and saving it to disk:

cam = Camera(0)
cam.open()
cam.record()  # starts recording

while cam.recordingTime < 5.0:  # record for 5 seconds
    if event.getKeys('q'):
        break
    cam.update()

cam.stop()  # stops recording
cam.save('myVideo.mp4')
cam.close()

Providing a microphone as follows enables audio recording:

mic = Microphone(0)
cam = Camera(0, mic=mic)

Overriding the default frame rate and size (if cameraLib supports it):

cam = Camera(0, frameRate=30, frameSize=(640, 480), cameraLib=u'opencv')

_assertCameraReady()[source]¶

Assert that the camera is ready. Raises a CameraNotReadyError if the camera is not ready.

_assertMediaPlayer()[source]¶

Assert that we have a media player instance open.

This will raise a RuntimeError if there is no player open. Use this function to ensure that a player is present before running subsequent code.

_download()[source]¶

Download video file to an online repository. Not implemented locally, needed for auto translate to JS.

_enqueueFrame()[source]¶

Pull waiting frames from the capture thread.

This function will pull frames from the capture thread and add them to the buffer. The last frame in the buffer will be set as the most recent frame (lastFrame).

Returns:

True if a frame has been enqueued. Returns False if the camera is not ready or if the stream was closed.

Return type:

bool

_upload()[source]¶

Upload video file to an online repository. Not implemented locally, needed for auto translate to JS.

authorize()[source]¶

Get permission to access the camera. Not implemented locally yet.

close()[source]¶

Close the camera.

This will close the camera stream and free up any resources used by the device. If the camera is currently recording, this will stop the recording, but will not discard any frames. You may still call save() to save the frames to disk.

property device¶

Camera to use (str or None).

String specifying the name of the camera to open a stream with. This must be set prior to calling start(). If the name is not valid, an error will be raised when start() is called.

property frameCount¶

Number of frames captured in the present recording (int).

property frameRate¶

Frame rate of the video stream (float or None).

Only valid after an open() and successive _enqueueFrame() call as metadata needs to be obtained from the stream. Returns None if not valid.

property frameSize¶

Size of the video frame obtained from recent metadata (float or None).

Only valid after an open() and successive _enqueueFrame() call as metadata needs to be obtained from the stream. Returns None if not valid.

static getCameraDescriptions(collapse=False)[source]¶

Get a mapping or list of camera descriptions.

Camera descriptions are a compact way of representing camera settings and formats. Description strings can be used to specify which camera device and format to use with it to the Camera class.

Descriptions have the following format (example):

'[Live! Cam Sync 1080p] 160x120@30fps, mjpeg'

This shows a specific camera format for the ‘Live! Cam Sync 1080p’ webcam which supports 160x120 frame size at 30 frames per second. The last value is the codec or pixel format used to decode the stream. Different pixel formats and codecs vary in performance.

Parameters:

collapse (bool) – Return camera information as string descriptions instead of CameraInfo objects. This provides a more compact way of representing camera formats in a (reasonably) human-readable format.

Returns:

Mapping (dict) of camera descriptions, where keys are camera names (str) and values are a list of format description strings associated with the camera. If collapse=True, all descriptions will be returned in a single flat list. This might be more useful for specifying camera formats from a single GUI list control.

Return type:

dict or list

static getCameras(cameraLib=None)[source]¶

Get information about installed cameras on this system.

Returns:

Mapping of camera information objects.

Return type:

dict

getLastClip()[source]¶

File path to the last saved recording.

This value is only valid if a previous recording has been saved to disk (save() was called).

Returns:

Path to the file the most recent call to save() created. Returns None if no file is ready.

Return type:

str or None

getMetadata()[source]¶

Get stream metadata.

Returns:

Metadata about the video stream, retrieved during the last frame update (_enqueueFrame call).

Return type:

MovieMetadata

getVideoFrame()[source]¶

Pull the most recent frame from the stream (if available).

Returns:

Most recent video frame. Returns NULL_MOVIE_FRAME_INFO if no frame was available, or we timed out.

Return type:

MovieFrame

property isNotStarted¶

True if the stream may not have started yet (bool). This status is given before open() or after close() has been called on this object.

property isReady¶

Is the camera ready (bool)?

The camera is ready when the following conditions are met. First, we’ve created a player interface and opened it. Second, we have received metadata about the stream. At this point we can assume that the camera is ‘hot’ and the stream is being read.

This is a legacy property used to support older versions of PsychoPy. The isOpened property should be used instead.

property isRecording¶

True if the video is presently recording (bool).

property isStarted¶

True if the stream has started (bool). This status is given after open() has been called on this object.

property isStopped¶

True if the recording has stopped (bool). This does not mean that the stream has stopped, getVideoFrame() will still yield frames until close() is called.

property lastClip¶

File path to the last recording (str or None).

This value is only valid if a previous recording has been saved successfully (save() was called), otherwise it will be set to None.

property lastFrame¶

Most recent frame pulled from the camera (VideoFrame) since the last call of getVideoFrame.

property metadata¶

Video metadata retrieved during the last frame update (MovieMetadata).

property mic¶

Microphone to record audio samples from during recording (Microphone or None).

If None, no audio will be recorded. Cannot be set after opening a camera stream.

open()[source]¶

Open the camera stream and begin decoding frames (if available).

This function returns when the camera is ready to start getting frames.

Call record() to start recording frames to memory. Captured frames came be saved to disk using save().

record()[source]¶

Start recording frames.

This function will start recording frames and audio (if available). The value of lastFrame will be updated as new frames arrive and the frameCount will increase. You can access image data for the most recent frame to be captured using lastFrame.

If this is called before open() the camera stream will be opened automatically. This is not recommended as it may incur a longer than expected delay in the recording start time.

Warning

If a recording has been previously made without calling save() it will be discarded if record() is called again.

property recordingBytes¶

Current size of the recording in bytes (int).

property recordingTime¶

Current recording timestamp (float).

This returns the timestamp of the last frame captured in the recording.

This value increases monotonically from the last record() call. It will reset once stop() is called. This value is invalid outside record() and stop() calls.

save(filename, useThreads=True, mergeAudio=True, encoderLib=None, encoderOpts=None)[source]¶

Save the last recording to file.

This will write frames to filename acquired since the last call of record() and subsequent stop(). If record() is called again before save(), the previous recording will be deleted and lost.

This is a slow operation and will block for some time depending on the length of the video. This can be sped up by setting useThreads=True.

Parameters:

• filename (str) – File to save the resulting video to, should include the extension.

• useThreads (bool) – Use threading where possible to speed up the saving process. If True, the video will be saved and composited in a separate thread and this function will return quickly. If False, the video will be saved and composited in the main thread and this function will block until the video is saved. Default is True.

• mergeAudio (bool) – Merge the audio track from the microphone with the video. If True, the audio track will be merged with the video. If False, the audio track will be saved to a separate file. Default is True.

• encoderLib (str or None) – Encoder library to use for saving the video. This can be either ‘ffpyplayer’ or ‘opencv’. If None, the same library that was used to open the camera stream. Default is None.

• encoderOpts (dict) – Options to pass to the encoder. This is a dictionary of options specific to the encoder library being used. See the documentation for ~psychopy.tools.movietools.MovieFileWriter for more details.

property status¶

Status flag for the camera (int).

Can be either RECORDING, STOPPED, STOPPING, or NOT_STARTED. This property used in Builder output scripts and does not update on its own.

stop()[source]¶

Stop recording frames and audio (if available).

property streamTime¶

Current stream time in seconds (float). This time increases monotonically from startup.

This is -1.0 if there is no active stream running or if the backend does not support this feature.

update()[source]¶

Acquire the newest data from the camera stream. If the Camera object is not being monitored by a ImageStim, this must be explicitly called.

property win¶

Window which frames are being presented (psychopy.visual.Window or None).

class psychopy.hardware.camera.CameraInfo(index=-1, name='Null', frameSize=(-1, -1), frameRate=-1.0, pixelFormat='Unknown', codecFormat='Unknown', cameraLib='Null', cameraAPI='Null')[source]¶

Information about a specific operating mode for a camera attached to the system.

Parameters:

• index (int) – Index of the camera. This is the enumeration for the camera which is used to identify and select it by the cameraLib. This value may differ between operating systems and the cameraLib being used.

• name (str) – Camera name retrieved by the OS. This may be a human-readable name (i.e. DirectShow on Windows), an index on MacOS or a path (e.g., /dev/video0 on Linux). If the cameraLib does not support this feature, then this value will be generated.

• frameSize (ArrayLike) – Resolution of the frame (w, h) in pixels.

• frameRate (ArrayLike) – Allowable framerate for this camera mode.

• pixelFormat (str) – Pixel format for the stream. If u’Null’, then codecFormat is being used to configure the camera.

• codecFormat (str) – Codec format for the stream. If u’Null’, then pixelFormat is being used to configure the camera. Usually this value is used for high-def stream formats.

• cameraLib (str) – Library used to access the camera. This can be either, ‘ffpyplayer’, ‘opencv’.

• cameraAPI (str) – API used to access the camera. This relates to the external interface being used by cameraLib to access the camera. This value can be: ‘AVFoundation’, ‘DirectShow’ or ‘Video4Linux2’.

property cameraAPI¶

Camera API in use to obtain this information (str).

property cameraLib¶

Camera library these settings are targeted towards (str).

property codecFormat¶

Codec format, may be used instead of pixelFormat for some configurations. Default is ‘’.

description()[source]¶

Get a description as a string.

For all backends, this value is guaranteed to be valid after the camera has been opened. Some backends may be able to provide this information before the camera is opened.

Returns:

Description of the camera format as a human readable string.

Return type:

str

property frameRate¶

Frame rate (float) or range (ArrayLike).

Depends on the backend being used. If a range is provided, then the first value is the maximum and the second value is the minimum frame rate.

property frameSize¶

Resolution (w, h) in pixels (ArrayLike or None).

frameSizeAsFormattedString()[source]¶

Get image size as as formatted string.

Returns:

Size formatted as ‘WxH’ (e.g. ‘480x320’).

Return type:

str

property index¶

Camera index (int). This is the enumerated index of this camera.

property name¶

Camera name (str). This is the camera name retrieved by the OS.

property pixelFormat¶

Video pixel format (str). An empty string indicates this field is not initialized.