Contents

Instructions for lecturers

Most lecturers now place material for their students onto the web. To support this, we create each year a new set of directories and page templates on the departmental filer and web server, to ensure that outdated material is not left in the main student access path.

Where are the files?

Each course has its own directory on the filer with a set of web-page templates.

These can be found this year

under Unix/Linux/macOS (via automounted NFS) at
```
/anfs/www/html/teaching/2122/courseid
```

under Windows (via SMB) at

\\filer.cl.cam.ac.uk\webserver\www\html\teaching\2122\courseid

under macOS (via SMB, not recommended, better use NFS) at

smb://wilbur.cl.cam.ac.uk/webserver/www/html/teaching/2122/courseid

on “the Interwebs” at

https://www.cl.cam.ac.uk/teaching/2122/courseid/
https://www.cl.cam.ac.uk/teaching/current/courseid/

Please consult the lecturer index to find your pages.

You can access the /anfs/www/... path above on the departmental file space directly on any lab-managed Linux computer. If you lack one, please use ssh to log into one of the Linux timesharing servers (e.g., ely.cl.cam.ac.uk). There are also new hints for Windows users.

You can also configure your own computers for automounted NFS access to the filer:

External lecturers: The instructions on this page are mainly aimed at lecturers who have already a login on a departmental Linux server. External lecturers may find it easiest to ask a member of the department, such as the teaching officer who sponsors their course, or the student administrators to place course materials for them onto our web server. Former members of the department, or technically keen external lecturers, may also ask a teaching officer to request for them a “discretionary Unix account” from [Javascript required], ideally sometimes in early July. (Note that remote access to Computer Laboratory servers is not entirely trivial, as password-based login from outside is disabled, and new users will have to set up VPN and Kerberos authentication first. See our sys-admin ssh pages for details.)

How to update the pages?

An easy to edit, undecorated, “bare-bones” HTML file, materials-b.html, has been placed into your directory, where you can add any information that you would like to make available to your students, such as links to lecture notes and exercise sheets. The actual “Course materials” page, materials.html, is automatically generated from that file after you type "make" under Linux. (If there is no materials-b.html file, you can edit index-b.html instead, but this applies only to a few pages where there is no syllabus.)

To recreate all the *.html files from the respective *-b.html files, run the UNIX command:

  /anfs/www/tools/bin/ucampas -r

Simply typing “make” will achieve the same, thanks to the also provided Makefile.

New this year:

Windows users may find the updated Ucampas from Windows instructions useful, which explain how to configure the SSH version that comes with the latest Windows 10 version 21H1. You no longer need PuTTY. They also provide a new Windows Shell extension that allows you to call “make” or “ucampas” from the context menu (right mouse click) in File Explorer. (Contact Markus Kuhn if you need help with that.)

Access rights

A principal lecturer has been assigned to each course. This person is the owner of the directory on the filer and has full access.

If a course has more than one lecturer, its course directory also gives write access to Unix group “teaching”, which comprises all the lecturers teaching any course at the department this year, plus teaching administrators (about 70 people). This makes collaboration easier in courses taught by several people, and also allows administrators to help with placing materials online or fixing typos. To preserve group write access, make sure the Linux command “umask” outputs “0002”.

If you prefer to disable group write access, you could do this with the Linux tools chgrp or chmod. However we do not recommend this: if user wwwupdate no longer has write access to auto-generated HTML files, the site navigation data on some of your pages may get out of date as we can no longer update it for you.

Access rights for web users, such as requiring Raven login and restricting access to lists of certain users or pre-defined groups, can be controlled by adding or editing a Require line in an .htaccess file in the directory that you want to restrict. (This is the same mechanism available elsewhere on the CL web space, such as your personal ~/public_html/ directory. See below for how such an .htaccess file controls access to your page for supervisors and your video recordings page by default).

Syllabus page

The first tab of the course pages (index.html) usually shows an HTML version of the syllabus. You are not supposed to edit that yourself directly: the syllabus is edited and frozen in August/September and substantial changes require teaching-committee approval.

To update your syllabus: You can fetch the current HTML source from either /anfs/www/html/teaching/2122/syllabus-html/ or you can click near the bottom of your syllabus page on “edit page” and there then on “download as HTML file”. Make your updates to that file, and send the result as an HTML attachment to Dinah Pounds (for undergraduate courses) or Lise Gough and Joy Rook (for masters modules).

Materials for supervisors

Lecturers in Part IA/IB/II are expected to prepare a Supervision Guide for supervisors of the course, and this is what the page “Information for supervisors” in subdirectory supervisors/ is for. Access to this page is restricted via Raven.

You can edit the file supervisors/.htaccess in order to grant access to individual supervisors that contact you, as explained in the comments in that file. Supervisors can also ask the Director of Studies or Helen Neal (whoever hired them), to add them to the Lookup/Raven group cl-supervisors, to gain that access. (Comments in the .htaccess file also explain how you can grant access to your students after the end of lectures and supervisions.)

In our archive of past Tripos exam papers, students can now also access solution notes older than two years (this year: for papers 1–7 only one year!). As a result, supervisors can no longer rely on past exam questions as exercise material and need separate exercise sheets and solution notes.

Assessment page

Part II units of assessment as well as Part III and MPhil ACS modules have an assessment-b.html page, where you need to explain in detail how you are going to assess the course. This might include information about deadlines for essays or the dates and details of exams, as well as how the final mark will be calculated from all the assessed student contributions.

If your Part II unit is also available as a Part III and MPhil ACS module, please make sure you populate the assessment-tab page on both of your course pages.

Cloned course pages

Some courses (in particular many of the “Part II units of assessment”) are offered to both Part II as well as Masters students. In these cases, we create two separate course directories for each group of students, using different course codes.

This is because while the lectures and most of the course materials may be the same, the form of assessment (and in some cases also the syllabus) will be different.

To avoid lecturers having to maintain two copies of their syllabus and course-materials pages, we have set up the syllabus and materials pages of these "cloned" Masters courses such that they automatically copy over the text from the respective Part II parent-course pages. This is done using a magic <div class="ucampas-include-html"> element, which extracts and copies the relevant HTML and also adjusts embedded URLs to work correctly. If you want, you can add additional text above or below that magic div element, or you can alternatively also delete it and replace it with your own manually maintained copy of your text, as you prefer. See the comments in the materials-b.html files for more details.

After each edit to the materials page of the parent course, make sure you also run ucampas on the corresponding cloned page to update it with the latest text. The default Makefile provided in your parent-course directory will do that automatically.

For the “Recordings” page, a different mechanism is used to update the clone. (The video/Makefile in the cloned page calls rsync to copy hardlinks of the files, and then calls ucampas to rebuild the page with adjusted navigation links.)

Video recordings

For the COVID-19 switch to online lectures, we have added an additional “Recordings” tab at

       /auto/anfs/www/html/teaching/2122/courseid/video/
= https://www.cl.cam.ac.uk/teaching/2122/courseid/video/

Record your lectures as *.mp4 files and copy them into the above video/ folder. You can then auto-generate an index page on Ely with

$ ssh -K ely.cl.cam.ac.uk
$ cd /anfs/www/html/teaching/2122/courseid/video/
$ make

The “make” command will run the “Makefile” in that folder. This will

extract one of the first frames of each *.mp4 file and save it as a *.jpg file (to be used as a preview image by the player)
call a script “/anfs/www/tools/bin/videopage *.mp4” that automatically builds an index.html file containing <video> player elements for all your *.mp4 videos in that folder, along with some metadata (length of your video).

This way, you get a make-generated video index page, without having to edit any HTML yourself. Each time you add another video file, simply call “make” again to update that index page. (If you instead want to edit your video index page manually, you may want to empty or change the Makefile such that it cannot accidentally overwrite your DIY index page if called.)

If you do not intend to use the “Recordings” tab, you can remove it in three steps:

delete from uconfig.txt the line video,
run "make"
delete the video/ subdirectory

By default, there is a file video/.htaccess with the line

Require group students-all cl-supervisors all-cl-users undergrad-directors-of-studies

This restricts access to the recordings tab to members of the department and others involved in teaching our courses. Please adjust this file for your access-control preferences, e.g. either

delete video/.htaccess to make your recordings openly available on the Internet,
replace it with the line Require valid-user to grant access to anyone with a Raven login,
add lines of the form Require user abc123 def467 to grant access to individual additional students using their CRSId.

If you run “make” on your own computer, make sure it has the “ffmpeg” tool (used to extract the preview *.jpg image) and the “Image::ExifTool” Perl library (used to extract video metadata) installed:

Ubuntu Linux: sudo apt-get install ffmpeg libimage-exiftool-perl
macOS with Homebrew: brew install ffmpeg exiftool

If you want to prefix your video index page with a few introductory remarks, then put these into a file intro.html in the video/ folder, which the videopage script will then include automatically.

Video file naming conventions

Your video files will appear on the auto-generated index page in alphabetical sorting order, so make sure each filename starts with a 2-digit number or yyyy-mm-dd date.

The videopage script understands several different file naming schemes, for example:

If you just want to have a sequence of videos, each with a part number and a title, use names such as
```
01-Introduction_and_prerequisites.mp4
02-Unix_history_and_free_software.mp4
03-Terminals.mp4
03.1-ASCII_and_Unicode.mp4
03.2-ESC_sequences.mp4
04-Documentation.mp4
[...]
```
(If you don’t get the above sorting order displayed with ls -l, you can set the environment variable LC_COLLATE=C to switch to a simpler sorting order.)
The videopage script will automatically convert filenames of that format into a nicer <h2> heading for each video, by removing any leading zero digits (needed to maintain sorting order) in the part number, removing the .mp4 extension, and converting any underscore in the title text into a space. So the above will be displayed as
1 Introduction and prerequisites
2 Unix history and free software
3 Terminals
3.1 ASCII and Unicode
3.2 ESC sequences
4 Documentation
[...]
.
(You can also always use a dot in the part number, to separate a lecture number from the number of the video within that lecture, e.g. 01.1-Introduction_and_prerequisites.mp4.)
Example: 1920/UnixTools/video/
Grouping recordings by lecture: Some students find it helpful to be told which recording they should watch on which day. If you add in a file sections.txt lines of the form recordings|heading, then the videopage script will automatically insert the given heading before the stated number of recordings. If you append the unit symbol min to recordings, the script will interpret that as a number of minutes rather than as a number of recordings, and will automatically split up the recordings into groups of (on average) that many minutes.
Example: 2021/DSP/video/sections.txt for the 2021/DSP/video/ page at /anfs/www/html/teaching/2021/DSP/video/.
If you want to group your videos by lecture date, then prefix each video filename with the yyyy-mm-dd date of the lecture, optionally followed by more digits (e.g. an integer, or the hh:mm start time of the recording) for sorting, such as
```
2020-04-24.mp4
2020-04-27_1.mp4
2020-04-27_2.mp4
2020-04-29.mp4
2020-05-01.mp4
[...]
```
Example: 1920/DSP/video/
(In this date-based format, there is currently not yet any provision for title text, as it was originally meant for automatically named recordings made in lecture theatres by just pressing a button.)

Reusing video recordings

Lecture recordings have a large file size compared to other course materials. If you reuse recordings (or other large files) from a previous year, please avoid simply copying them each year, in the interest of saving disk space. Instead, you can use either hard links (Unix command: ln or cp -l) or symbolic links (Unix command: ln -s or cp -s) to simply create each year another reference to an existing file on the filer. This makes an existing file reachable from the new folder without occupying additional disk space. Create either type of link from a Linux command line via NFS; neither the Windows Explorer nor the macOS Finder understand links, and they are not recognisable as links via SMB on our filer. Don’t use Windows “shortcuts” or Finder “aliases”, as Linux tools (including the web server) won’t understand these. Hard links have the advantage that adding a new hard link will cause the file to remain in place even after it gets deleted at its old location. Symbolic links instead have the advantage that you can explicitly see (with ls -l) from where the referenced file comes from originally. In either case: before overwriting a linked file, always consider if you don’t want to delete the link first, to avoid overwriting the original file.

Example:

$ cd /anfs/www/html/teaching/2122/TeX+MATLAB/video/
$ cp -l ../../../2021/TeX+MATLAB/video/*.mp4 .
$ make

Video recording tips

There is no reason to make each pre-recorded video 50 minutes long. Better break up your pre-recorded lecture into topic sections of 5–20 minutes each, and record each of these as a separate file. This makes it easier for students to take a break, or do some exercises, at the appropriate time.
Make sure the first couple of seconds of your video indicate what the video is about, e.g. shows a slide that states or visualizes the topic of the section. The index page will show a frame taken after the first second of each video, as a pre-view picture, so if it indicates the section, that helps your students to pick the right video. (You may want to define keyboard hotkeys to start and stop the recording, such that the start of your videos does not show you interacting with the GUI of your screen recording software.)
You can use any video recording software that you like, as long as it produces reasonably sized MP4 (H.264) files compatible with most web browsers. Make sure you use variable bitrate (VBR) encoding. For example, OBS Studio set up via the “auto-configuration wizard” (Tools>Auto-configuration wizard) in “Optimize just for recording” works well. (The alternative, constant bitrate (CBR) encoding, commonly used for real-time streaming, produces many megabits per second even for a completely static image, leading to huge files. 100 MB per hour is a reasonable typical VBR filesize, while 10 GB per hour is not!)
See Markus Kuhn’s page on OBS Studio settings for suggested settings if you are using OBS Studio for recording.
There is also a departmental Google Docs document with more video-recording hints that we collected for Easter term 2020.

Captions

If you would like to add captions to your videos, you can place these in WebVTT format as a *.vtt file next to your *.mp4 file. The videopage tool will then automatically point the video player at them.

One way of obtaining a *.vtt captions file for a recording is to temporarily upload your MP4 file to Microsoft Stream:

Sign in to Microsoft Stream with your University Office365 login
Go to Create / Upload video to upload your MP4
Wait until the transcript of your video appears (this can take a few tens of minutes).
Go to ... / Update video details / Captions / download file to download your transcript.
You can now delete your video again from Microsoft Stream.
Rename the downloaded WebVTT file into the same filename as your video recording, except that you replace the extension .mp4 with .vtt, and move it into your video folder.
You can use the tool /anfs/www/tools/bin/vtt strip filename.vtt >newname.vtt to obtain an uncluttered version, with Microsoft Stream metadata removed (for easier editing).

In your video folder, use rm index-b.html ; make to rebuild the index page after adding/renaming any *.vtt file. The video player should now offer you a button or menu item to switch on “Captions”. Example: LaTeX introduction

Making corrections to captions: Use any text editor to fix errors in automatically transcribed captions files. Once you have proofread a filename.vtt file, please rename it into filename_checked.vtt to indicate that these captions have now been manually checked for correctness (and are not just AI guesswork). Then rebuild the index file as before. You should now see a checkmark after the vtt download link and the suffix “(checked)” in the captions menu. Such manually checked WebVTT files will also be collected regularly in an index of recordings with manually checked captions, which is available as training data for people interested in building better custom speech-recognition models for departmental lecture recordings.

Automatic speech recognition with a custom model: Cloud-based automatic speech transcription services (in Microsoft Streams, Google Docs, Youtube, Panopto, etc.) will lack in their dictionary many technical terms and names that appear in your lectures. Their output will therefore often need heavy editing to become useful. There may soon be an in-house text-to-speech facility available that can fix this, by being re-trained regularly with WebVTT transcripts of your recordings that you have already checked and corrected, such that it then can also recognize your own technical vocabulary and pronunciation. More information on this may appear here soon; until then Andrew Caines (apc38) and Tom Cusack (tc531) in the NLP group can provide details.

More information

Getting started with HTML – if you have never edited a web page
HTML 4 specification
Ucampas documentation – explains how to add additional pages or use advanced features (auto-generated tables of content, etc.).
Creating the course web pages – instructions for pagemaster
Updating course syllabi and metadata – instructions for administrators