Expyriment 1.0.0

[fladd]

Aug 2025

For installation instructions, please see https://docs.expyriment.org/Installation.html!

New Features:

• Expyriment is now based on Pygame 2 (using SDL 2) and depends also on
  numpy & mediadecoder
• It's no longer necessary to install additional features via pip with
  [feature], since all dependencies are installed by default.
• test suite:
  • option to run single tests
  • improvements in reporting visual timing test results
  • improved audio test
  • format changes in saved protocol
• command line interface:
  • option -I starts an interactive session
  • option --display defines which display to show the (fullscreen)
    window on
  • option --display-resolution sets the fullscreen resolution to use
    (overwrites automatically detected maximal display resolution)
  • option --text-size sets the default experiment text size (as defined
    in design.defaults.experiment_text_size)
  • option --window-size sets the default size of the window (when using
    window-mode)
• all wait methods have new parameter low_performance which allows for
  other threads to be processed while waiting (at the cost of accuracy)
• control.Keyboard.process_control_events:
  • new parameter event_detected_function to set a function that is
    called as soon as a quit event is detected (but before the end function
    is called)
  • new parameter quit_denied_function to set a function that is called
    when a user declines the quitting (i.e. presses "n")
• control.Mouse.process_quit_event:
  • new parameter event_detected_function to set a function that is
    called as soon as a quit event is detected (but before the end function
    is called)
  • new parameter quit_confirmed_function to set a function that is
    called when a user confirms the quitting (i.e. presses "y")
  • new parameter quit_denied_function to set a function that is called
    when a user declines the quitting (i.e. presses "n")
• control.pause: added text and key parameters
• control.defaults:
  • added display to set display index for showing screen on
  • added display_resolution to overwrite detected native resolution
  • added audiosystem_device to select audio device
• stimuli.Audio:
  • not limited to .wav/.ogg files anymore
  • should support most common formats (i.e. WAV, AIFF, MP3, Ogg, Opus, FLAC)
  • new property is_playing to check whether the audio stimulus is
    playing
  • new property length to get the length of the audio stimulus
  • new property time to get the current playback time
  • new method wait_time to wait until specified playback time is reached
  • new method wait_end to wait until the audio stimulus has finished
    playing
  • new method pause to pause (and unpause) playback of the audio stimulus
  • new method seek to seek to a specified playback time
  • new method forward to forward playback by specified duration
  • new method rewind to rewind playback by specified duration or to the
    start
  • seek, rewind, forward, wait_time methods all take multiple
    convenient time formats now (e.g. "00:01:30")
• stimuli.Video:
  • general improvements
  • Pygame video backend removed (always relies on mediadecoder)
  • Pygame audio backend is now the default (instead of sounddevice)
  • new parameter audio_backend
  • new stimuli default video_audio_backend
  • Pygame audio backend uses current audiosystem (if started)
  • present method will start playback if not started already
  • frame dropping check is now located in update method (was in present)
  • update method allows for updating without blocking on vertical retrace
    (OpenGL mode only)
  • new property n_frames to get the total number of frames of the video
  • new property fps to get the frame rate in frames per second
  • new method wait_time to wait until a certain time
  • new method seek to seek to any position in the video
  • seek, rewind, forward, wait_time methods all take multiple
    convenient time formats now (e.g. "00:01:30")
• io.Screen:
  • new method get_display_resolution
  • new method misc.get_display_info
  • update method has new blocking parameter to control blocking on
    vertical retrace (OpenGL mode only) behaviour per call
• io.TextInput: get method now has parameter clear_event_cue
• misc:
  • new classMediaTime for representing time as used in the context of
    media playback
  • new function misc.get_audio_devices to get a list of available audio
    devices

Changed:

• Python 2 support has been removed
  Expyriment now only works with Python 3.9 or higher

• deprecated and obsolete classes, methods and parameter were removed

  • parameter experiment in control.start
  • permute.balanced_latin_square(), permute.cycled_latin_square()
  • geometry.position2coordinate(), geometry.points_to_vertice()
  • statistics.frequence_table()
  • stimulus.Dot, stimulus. Frame
  • Clock.cpu_time()
  • Visual.replace()
  • Circle.get_polar_coordiantes(), Circle.set_polar_coordinates()
  • FixCross.cross_size
  • Shape.is_point_inside(), Shape.is_shape_overlapping()

• package building with flit and pyproject.toml

• revision number and build data (__revision__, __date__) removed from
  source files

• Python 2 support has been removed
  Expyriment now only works with Python 3.10 or higher

• Documentation not shipped with Expyriment anymore (i.e. no offline
  documentation available, only online)

• rewrite of permutation module

• pause_key has been removed

• When running in virtual environment, Expyriment settings folder will be local
  to that environment

• Always use maximal display resolution by default for fullscreen mode (unless
  overwritten by control.defaults.display_resolution)

• expyriment.control.defaults.openg_gl is now called
  expyriment.control.defaults.opengl

• OpenGL mode "3" has been removed: OpenGL mode "2" (default) now does what
  "3" used to do (i.e. "alternative blocking")

• updated command line interface options:

  • -0, -g, --no-opengl, -1, -2, -3 are deprecated
  • OpenGL mode can now be set with new option --opengl
  • all arguments are now also available as alternative long names

• io.TextMenu: width is now an optional parameter. If not defined, surface
  width is based on the widest item in the menu

• io.GamePad.wait_press: removed time.sleep(0.0005)

• Deprecated io.Screen.get_monitor_resolution and misc.get_monitor_resolution

• misc.get_system_info:

  • additions and improvements
  • format changes for as_text output

• renaming: misc.py2py3_sort_array() to misc.string_sort_array()

• more consistent function naming in misc:

  • byte2unicode() to bytes_to_unicode()
  • unicode2byte() to unicode_to_bytes()
  • str2unicode() to str_to_unicode()
  • unicode2str() to unicode_to_str()
  • number2ascii() to numpad_digit_code_to_ascii()

• more consistent function naming in misc.geometry:

  • position2coordinates() to position_to_coordinates()
  • coordinates2position() to coordinates_to_position()
  • cartesian2polar() to cartesian_to_polar()
  • position2visual_angle() to position_to_visual_angle()
  • tuples2points() to tuples_to_points()
  • polar2cartesian() to polar_to_cartesian()

• components with American spelling are now also available in British spelling,
  enhancing consistency with the overall spelling in the library:

  • method control.initialize -> control.initialise
  • module design.randomize -> design.randomise
  • property design.Experiment.is_initialized ->
    design.Experiment.is_initialised
  • property design.Experiment.bws_factor_randomized ->
    design.Experiment.bws_factor_randomised
  • constant control.defaults.initialize_delay ->
    control.defaults.initialise_delay

Fixed:

• bug in colour.is_hex & colour.is_colour
• data_preprocessing: adds suffix ".csv" to filename when writing csv files
• bug when reusing subject id within a minute
• test suite: close serial port after test
• io.Keyboard: 0.5 ms timing inaccuracy in wait methods
• Visual stimuli: don't clear the original canvas when copying
• stimuli.Ellipse: bug when using uneven line_width values
• io.Screen: bug in saving screenshots with save when using OpenGL
• io.Screen: bug in showing Expyriment logo in task bar
• bug in misc.get_display_info
• several bugs in misc.get_system_info

---

This discussion was created from the release Expyriment 1.0.0.